Command line options

Find sequences of pulses corresponding to bursts from registered tags

Usage: find_tags_motus [OPTIONS] [TAG_DATABASE] [OUTPUT_DB] [INPUT_FILE]

where OPTIONS are described below, and

TAG_DATABASE is equivalent to --tag_database TAG_DATABASE
OUTPUT_DB is equivalent to --output_db OUTPUT_DB
INPUT_FILE is equivalent to --input_file INPUT_FILE

Option	Description
--help	print help
-f [ --default_freq ] arg (=166.376)	the default antenna frequency, in MHz. Although input data files contain frequency-setting records, this option can be used to set the frequency when processing a fragment of an input file that doesn't contain an initial frequency setting
-F [ --force_default_freq ] [=arg(=1)] (=0)	Ignore frequency settings in the input dataset; always assume all receivers are tuned to the default frequency
-m [ --min_dfreq ] arg (=-inf)	minimum offset frequency, in kHz. Pulses with smaller offset frequency are dropped.
-M [ --max_dfreq ] arg (=inf)	maximum offset frequency, in kHz. Pulses with larger offset frequency are dropped.
-u [ --unsigned_dfreq ] [=arg(=1)] (=0)	ignore the sign of frequency offsets, as some versions of the pulse detection code do a poor job of estimating a negative frequency
-s [ --frequency_slop ] arg (=0.5)	tag frequency slop, in KHz. A tag burst will only be recognized if its bandwidth (i.e. range of frequencies of its component pulses) is within FSLOP. This limit applies across all bursts within a sequence
-p [ --pulse_slop ] arg (=1.5)	how much to allow time between consecutive pulses in a burst to differ from measured tag values, in milliseconds
-b [ --burst_slop ] arg (=10)	how much to allow time between consecutive bursts to differ from measure tag values, in millseconds.
-B [ --burst_slop_expansion ] arg (=1)	how much to increase burst slop for each missed burst in milliseconds; meant to allow for clock drift
-T [ --timestamp_wonkiness ] arg (=0)	try to correct clock jumps in Lotek .DTA input data, where the clock sometimes jumps back and forth by an integer number of seconds. MAX_JUM is a small integer, giving the maximum amount by which the clock can jump and the maximum rounded number of cumulative jumped seconds in a run (the two use the same parameter value because the jumps are assumed to be unbiased. This option is only permitted if --lotek is specified. FIXME: only values of 0 or 1 are currently supported
--input_file arg	if src_sqlite is specified, this is a .sqlite database which contain table files (for sensorgnomes) or table DTAtags (for Lotek receivers). Otherwise, it is a .csv file, defaulting to stdin if not specified. Raw receiver records are read from the specified file.
-Q [ --src_sqlite ] [=arg(=1)] (=0)	Treat input_file as an sqlite database and fetch paths to compressed data files from the files table if a sensorgnome, or from the DTAtags table if a Lotek receiver.
-L [ --lotek ] [=arg(=1)] (=0)	Indicates that input data come from a lotek receiver. In this case, input lines have a different format: TS,ID,ANT,SIG,ANTFREQ,GAIN,CODESET with: [TS: real timestamp (seconds since the unix epoch), ID: lotek tag ID, ANT: single digit, SIG: signal strength in Lotek receiver units, GAIN: receiver gain setting, in Lotek receiver units, CODESET: 'Lotek3' or 'Lotek4'] Each input record is used to generate a sequence of pulse records in SG format,and the program re-finds tags from these.
--tag_database arg	.sqlite file which contains the tags (and possibly events) tables that define the tags to be sought (and possibly their activation history
-e [ --use_events ] [=arg(=1)] (=0)	Limit the search for specific tags to periods of time when they are know to be active. These periods are specified by a table in the tag database called 'events', which must have at least the columns 'ts', 'motusTagID' and 'event',where 'ts' (double) is the timestamp for event, in seconds since 1 Jan 1970 GMT;'tagID' (int) is the motus tagID; and 'event'(int) is 1 for activation, 0 for deactivation. In almost all cases, you want this option, as it lets the tag finder search for a changing set of tags over the time period it processes. Note: If this option is not specified, then all tags in the database are soughtand their detections reported over the entire timespan of the input file.
-n [ --bootnum ] arg (=1)	monotonic boot session for this run. Each boot session (time between reboots) for a receiver is processed by a separate invocation of find_tags_motus. The batch generated by the current invocation run will be associated with the specified bootnum in the output database.
-r [ --resume ] [=arg(=1)] (=0)	Attempt to resume tag finding where it left off for this boot session. This means: 1 - seek to the end of the previously-processed input timestamp, or to new line with the same timestamp as was saved 2 - any active tag runs and candidates are resumed
--output_db arg	.sqlite file which contains tables hits, runs, batches, etc. where output from this program will be stored; this is typically a .motus receiver database
--info_only [=arg(=1)] (=0)	only print program version and parameter info in JSON format, then exit
-t [ --test_only ] [=arg(=1)] (=0)	verify that the tag database is valid and that all tags in it can be distinguished with the specified algorithm parameters. If the database is valid and all tags are distinguishable, the program prints 'Okay\n' to stderr and the exit code is 0. Otherwise, the exit code is -1 and an error message is printed to stderr.
-g [ --graph_only ] [=arg(=1)] (=0)	Output a 'graphviz'-format file describing the transition graph for each nominal frequency. These files will be called graph1.gv, graph2, gv, etc. You can visualize using the 'dot' program from http:graphviz.org like so: dot -Tsvg graph1.gv > graph1.sv and then view graph1.svg in a web browser or inkscape https://inkscape.org. If you specify this option, the program quits without processing any input data.
-P [ --pulses_only ] [=arg(=1)] (=0)	Only output a table called pulses with these columns: batchID batch number, ts timestamp, ant antenna number, antFreq (MHz) antenna listen frequency, dfreq (kHz) offset frequency of pulse, sig relative pulse signal strength (dB max), noise relative noise strength (dB max), With this option, the program ignores the tag database (although it must still be specified) and only uses these options: --default_freq, --force_default_freq, --min_dfreq, --max_dfreq
-G [ --gps_min_dt ] arg (=3600)	Minimum time step, in seconds, between GPS fixes to be recorded from receiver data. A negative value means do not record any GPS timestamps to the output database.
-R [ --max_pulse_rate ] arg (=0)	maximum pulse rate (pulses per second) during pulse rate time window.Use to prevent exorbitant memory usage and execution time when noise-or bug-induced pulse bursts are present. Pulses from periods of length PULSERATEWIN (specified by --pulse_rate_window) where the pulse rate exceeds MAXPULSERATE are simply discarded. When max_pulse_rate=0, no rate limiting is performed
-w [ --pulse_rate_window ] arg (=60)	time window (seconds) over which pulse_rate is measured. When pulse_rate exceeds the value specified by max_pulse_rate during a period of this many seconds, all pulses in that period are discarded. This parameter is only used if max_pulse_rate is specified)
-X [ --min_bogus_spacing ] arg (=600)	minimum time in seconds between emitting a bogus tag ID that indicates suppression of noisy input. FIXME: no bogus tag ID is currently emitted when suppressing noisy input. See Tag_Candidate::dump_bogus_burst()
-c [ --pulses_to_confirm ] arg (=4)	how many pulses must be detected before a hit is confirmed. Forcmore stringent filtering when BSLOP is large, CONFIRM should be set to 2*PULSES_PER_BURST or larger, so that more gaps must match those registered for a given tag before a hit is output.
-l [ --sig_slop ] arg (=10)	tag signal strength slop, in dB. A tag burst will only be recognized if its dynamic range (i.e. range of signal strengths of its component pulse is within SSLOP. This limit applies within each burst of a sequence. Note: if SSLOP < 0, this means to ignore signal strength, which is appropriate for sources where signal strength is not in DB units, e.g. Lotek .DTA files
-S [ --max_skipped_bursts ] arg (=60)	maximum number of consecutive bursts that can be missing (skipped) without terminating a run. When using the pulses_to_confirm criterionthat number of pulses must occur with no gaps larger than max_skipped_bursts bursts between them.
-x [ --external_param ] arg	record an external parameter for this batch. This parameter's value should look like NAME=VALUE, where VALUE is a number. This option can be used multiple times. Note: the commit hash from the tag database's meta table is automatically recorded as external parameter metadata_hash to avoid a race condition, so this option should not be used for that purpose.