clarify: report on or claim ambiguous tag detections
In jbrzusto/motusClient: fetch data from the motus data server

Description Usage Arguments Details Value Author(s) Examples

A detections is "ambiguous" if the motus tag finder could not tell which of several tags was detected, because they all produce the same signal and were active at the same time. The motus tag finder uses tag deployment and lifetime metadata to decide what tags to seek when, and notices when it can't distinguish between two or more of them. Detections of such tags during these periods of overlap are assigned a negative motus tag ID that represents from 2 to 6 possible real motus tags. The ambiguities might be real (i.e. two or more tags transmitting the same signal and active at the same time), or due to errors in tag registration or deployment metadata.

1	clarify(s, id, from, to, all.mine = FALSE)

`s`	dplyr::src to the tag database, as returned by `tagme()`
`id`	if not missing, a vector of negative motus ambiguous tag IDs for which you wish to claim detections. If missing, all tags are claimed over any period specified by `from` and `to`.
`from`	if not missing, the start time for your claim to ambiguous detections of tag(s) `id`. If missing, you are claiming all detections up to `to`. `from` can be a numeric timestamp, or a character string compatible with `lubridate::ymd`
`to`	if not missing, the end time for your claim to ambiguous detections of tag(s) `id`. If missing, you are claiming all detections after `from`. `to` can be a numeric timestamp, or a character string compatible with `lubridate::ymd`
`all.mine`	logical; if TRUE, claim all ambiguous detections. In this case, `id, from` and `to` are ignored. If both `from` and `to` are missing, then all detections of ambiguous tag(s) `id` are claimed. Parameters `id`, `from`, and `to` are recycled to the length of the longest item. When you claim an ambiguous tag `T` for a period, any runs of `T` which overlap that period at all are claimd entirely, even if they extend beyond the period; i.e. runs are not split.

This function serves two purposes:

called with only a database dplyr::src, it reports the numbers of ambiguous detections and what they could represent.
called with id, it lets you claim some of the ambiguities as your own tag, so that in subsequent processing, they will appear to be yours.

This function does not (yet?) report your claim to motus.org

WARNING: you cannot undo a claim within a copy of the database. If unsure, copy the .motus file first, then run clarify on only one copy.

with no parameters, returns a summary data frame of ambiguous tag detections, with these columns

ambigID; integer: negative motus ambiguous tag ID, representing multiple possible real tags
numHits; numeric: total number of detections of this ambiguity
id1; integer: first possible motus ID of real tag that this detection might represent
fullID1; character: fullID for first possible real tag, in "Project#MFGID:BI@NOMFREQ(M.MotusID)" format
id2; integer: second possible motus ID of real tag that this detection might represent
fullID2; character: fullID for second possible real tag, in same format as fullID1
...
id6; integer: sixth possible motus ID of real tag that this detection might represent
fullID6; character: fullID for sixth possible real tag, in same format as fullID1
motusTagID; integer tag ID ambiguity was resolved to over some period
tsStart; numeric: timestamp of start of period for this ambiguity resolution
tsEnd; numeric: timestamp of end of period for this ambiguity resolution

John Brzustowski jbrzusto@REMOVE_THIS_PART_fastmail.fm

## s = tagme(57) ## get a dplyr::src to the tag database for project 57
## clarify(s)  ## report on the ambiguous tag detections in s
## clarify(all.mine=TRUE) ## claim all ambiguous tag detections as mine
## clarify(id = -57) ## claim all detections of ambiguous tag -57 as mine
## clarify(id = c(-72, -88, -91), from=("2017-01-02"), to=("2017-05-06")) ## claim all detections of ambiguous tags -72, -88, and -91 from
##   January 2 through May 6, 2017, as mine