find_tags: assemble putative pulses from coded ID tags and connect them into runs of tag detections.

Note: uses a slightly patched version of boost program_options (v 1.60.0) which always uses the last specified value for any non-vector option. This simplifies option overrides. See: jbrzusto/find_tags#67

There are two versions of the program: find_tags_motus and find_tags_unifile To build find_tags_motus, use the master branch. To build find_tags_unifile, use the find_tags_unifile branch.

Note: for convenience of Windows users who wish to run the program, a compiled binary version of find_tags_unifile is available here.

The Windows version is untested - use at own risk.

find_tags_motus	find_tags_unifile
runs on motus data processing server	runs on sensorgnome receivers(*)
has access to full Lotek codeset and all registered tags	only detects tags registered by the receiver owner and stored in a database on the receiver
works from a tag event table that reflects deployment history and estimated lifespan of each tag	works from a static list of tags, assumed to always be active
reads input from archived raw receiver files, indexed in an .sqlite database	reads input from stdin
writes output in batch/run/hit format to an sqlite DB	writes csv-formatted output to stdout
works with files from both sensorgnomes and Lotek receivers	only works with output from the sensorgnome pulse detector
records receiver parameter settings, GPS fixes, pulseCounts	ignores non-pulse records except for frequency setting
records how it was run in the receiver database	no record of how it was run
can save state and resume processing when new data for the same receiver arrive (possibly months later)	cannot be paused and resumed
handles tag ambiguities wherein two or more indistinguishalbe tags are active during the same period; ambiguous detections are reported as such	static tag list cannot contain any indistinguishable pairs of tags
built from master branch by git checkout master; make clean; make find_tags_motus	built from find_tags_unifile tag by git checkout find_tags_unifile;make clean; make find_tags_unifile

(*): find_tags_unifile is also used in the tag registration process on the data processing server; it uses the database of all Lotek ID codes to detect tag bursts in user-submitted .WAV recordings.

The algorithm uses a collection of DFAs walking a directed graph whose nodes are sets of tags, and whose edges are sets of gap-length ranges. The graph changes dynamically in response to tag activation and expiration events. Each DFA is a Tag_Candidate, which represents a possible real tag. The DFA accepts sequences of inter-pulse gaps compatible with the temporal pattern of one or more registered tags, subject to filtering by signal strength and offset frequency consistency. As the DFA accepts more pulses, the set of tags compatible with them shrinks, until eventually (hopefully) it reaches a single tag. The algorithm is greedy in that once a tag candidate has reached a (selectable) degree of further confirmation (i.e. accepted enough additional pulses), any other candidates sharing pulses with it are discarded. Such confirmed Tag_Candidates output a summary of each burst of pulses from their tag, as these are recognized. This summary constitutes a tag detection.

A set of DFAs operating on a single antenna and nominal frequency is called a Tag_Finder. The collection of all Tag_Finders is a Tag_Foray.

This algorithm explores only a small portion of the full "pulse-to-tag-assignment-problem" solution space, pruning many potential solutions early on. However, any pulse which passes frequency-offset band filtering will be considered for inclusion in a tag burst. If the pulse is not accepted by any confirmed Tag_Candidate, a new Tag_Candidate is created containing just that pulse.