During localization, clarify need for trimming and add check/warning

[rhine3]

To use the acoustic localization pipeline, it is currently not clear that synchronized recordings must be trimmed prior to detection. This is required to ensure that detections occur during the same time windows. Otherwise, detection outputs from classifiers wouldn’t line up. E.g., if one recording has a start time that’s 2s offset of another recording, their detection dataframes will be offset:

filename, start_timestamp, end_timestamp, OVEN
A1.wav, 6:00:00.0, 6:00:03.0, 1
A1.wav, 6:00:03.0, 6:00:06.0, 1
A2.wav, 6:00:02.0, 6:00.05.0, 1
A2.wav, 6:00:05.0, 6:00:08.0, 0

The pipeline currently groups detections by their start_timestamp, so recordings that potentially contain the same sound, but have misaligned detection time-windows, would not be included in the same position estimation.

Note that offset/staggered detection times could also occur due to overlapping detection time windows.

Some suggestions:

• Add a check for correct trimming, e.g.:
  • get expected window length from clip_len = detections.end_timestamp[0] - detections.start_timestamp[0]
  • check all start_timestamps fit the pattern min(detections.start_timestamp) + x * clip_len where x is any integer. Note, detection could be done with overlapping time windows, so this might not be the best way to check for correctly aligned recordings.
  • produce a warning error if this is untrue. Warning should mention the need for aligned time-windows.
• Clarify this front and center in the docs, emphasizing the need to trim to a multiple of the clip length, e.g., by changing the text at the top of the notebook to something like this:

  2. Synchronizing recordings
  3. Trimming or extending recordings to start at the same time, or a multiple of your labeling window (e.g., desired classifier's input clip length)
  4. Label the presence of your sound of interest in short windows in each recording, e.g., using a classifier or other labeling technique