Merge N simulated detectors into a matchbox-native capture history table

Generalizes the original two-detector merge to any number N >= 2 of simulated detectors, and aligns the output columns with matchbox's own canonical convention (key, t0/tEnd, detect_observerK, <col>_observerK for every other column, suffixed and NA where that detector missed the event) – rather than the ad hoc consolidated (SNR, signalRMSdB, ...) columns this function used to build to match a now-superseded MATLAB format. Downstream consolidation across observers (e.g. averaging SNR) is chtToSNRinfo's job, via its own signalCol/ noiseCol vector-averaging support – not this function's.

Detectors are matched by exact datetime equality, not the temporal-overlap clustering real matchbox tables use for actual bounded detections. This is deliberate, not a shortcut: every detector here runs against the same underlying simulated call population (via simulateDetector), so a true positive's datetime is bit-identical across every detector that examined it, while each detector's own false positives get independently random datetimes with a negligible chance of colliding with anyone else's. Real acoustic detections need fuzzy overlap-based matching precisely because their bounds are imprecise; these simulated point-in-time detections don't have that problem to begin with.

fLow/fHigh (matchbox's frequency-envelope columns) are deliberately omitted: this simulation pipeline never models frequency at all, so there is nothing real to put there. The result is a plain data.frame, so add them yourself later if a specific analysis needs them.

Usage

simsTocaptureHistoryTable(..., observerSuffix = NULL)

Arguments

...

Two or more data.frames, each the output of simulateDetector for one simulated detector, sharing a datetime column.

observerSuffix

Character vector, one name per detector in ..., used to suffix every one of that detector's own columns (detect_<suffix>, snr_<suffix>, groundTruth_<suffix>, etc.) in the output. Default paste0('observer', seq_along(list(...))) – matchbox-native, matching chtToSNRinfo's own default observers naming, so a simulated capture history table needs no renaming before use. Pass e.g. c('table1','table2') for the older detect_table1/detect_table2 shape some existing tests and fixtures still key on.

Value

A data.frame with one row per matched event: key (sequential event id), t0/tEnd (both the shared event time, as a genuine MATLAB datenum via Rdate2mat – matching real matchbox's own t0/tEnd encoding, so chtToSNRinfo()'s default timeCol='t0' and cde()'s timeCol=NULL auto-detection both work unmodified on this table), datetime (the original, exact POSIXct, kept for anyone who wants a directly readable time rather than a datenum), detect_<suffix> (logical, per detector, FALSE where that detector examined the event and missed it), groundTruth (coalesced across detectors – see Details – present only when the inputs have their own groundTruth column, as simulateDetector's output does), and every other column from each detector's own output, suffixed _<suffix> and NA wherever that detector has no row for the event at all (this includes a per-observer groundTruth_<suffix> alongside the coalesced groundTruth).