synchronize: Synchronize Hyfe detections with a set of labels
In hyfe-ai/hyfer: R Utilities for Interacting with Hyfe Data

Description Usage Arguments Details Value

Comparing Hyfe performance to a groundtruth, such as a set of labeled detections, requires that the two sets of events are synchronized. Even if Hyfe's system time differs from the labeler's clock by a second or two, that offset can complicate and confuse the performance evaluation process.

synchronize(
  reference_times,
  reference_labels = NULL,
  hyfe_times,
  hyfe_predictions = NULL,
  filter_to_3 = TRUE,
  toplot = TRUE,
  verbose = TRUE
)

`reference_times`	A vector of numeric timestamps (seconds since 00:00:00 UTC on January 1, 1970). These are the reference times to which the Hyfe detection times will be compared. For example, the timestamps of a labelled sound can serve as a reference time.
`reference_labels`	A numeric vector of labels the same length as `reference_times`. If `NULL`, the function will assume that all reference times refer to a true cough event. These labels are interpreted using Hyfe's 4-tier labeling system (0= definitely not a cough; 1 = disputable that this is an authentic or audible cough; 2 = definitely an authentic cough, but distant; 3 = an authentic and loud cough).
`hyfe_times`	A vector of numeric timestamps of Hyfe detections.
`filter_to_3`	If `TRUE` (the default), the reference times will be filtered to those that are definitely a loud cough.
`toplot`	If `TRUE`, a diagnostic plot will be shown.
`verbose`	Print status updates to the Console?
`hyfe_predicitons`	A logical vector of predictions the same length as `hyfe_times`. If `NULL`, the function will assume that all Hyfe times refer to cough predictions.

This functions synchronizes Hyfe detections to the set of reference/label times.

This function uses a three-stage iterative method for identifying the offset that reduces the total offset error between reference times and Hyfe times. The first stage tests for hour-scale offsets, such as timezone differences. The second stage tests for minute-scale offsets. The final stage tests for half-second scale offsets. These three offsets are summed and returned.

A numeric estimate of Hyfe's time offset, in seconds, from the reference times. A negative number indicates that Hyfe is ahead of the reference times. In most cases, your next step in analysis will be yo add the return of this function to your Hyfe times.

Note that this output is almost always a single number, but sometimes two (or more) different offsets can yield an equal reduction in error and therefore be equally viable offsets. In those instances, all viable offsets are returned.

hyfe-ai/hyfer documentation built on Dec. 20, 2021, 5:53 p.m.