Checks a table of detections and returns it in the form mrds::ddf()
expects. sweep_models() calls it before fitting. It is exported so the
checks can be run on their own before a sweep.
Arguments
- data
Data frame, one row per detection. Needs a numeric
distancecolumn (exact) or numericdistbeginanddistendcolumns (binned). Optional columns:object(detection ID) anddistance_source.- truncation
Number. Right truncation distance, in the units of the distances. Required.
- left
Number or
NULL(default). Left truncation distance.NULLmeans no left truncation.- breaks
Numeric vector or
NULL(default). Bin cutpoints for binned data, strictly increasing. Derived from the bins whenNULL. Ignored, with a warning, for exact data.
Value
A list:
dataThe prepared data frame, ready for
mrds::ddf().binnedTRUEfor binned data,FALSEfor exact.breaksThe cutpoints used (binned), or
NULL(exact).n_droppedNumber of input rows not in
data.droppedNamed integer vector splitting the drops by reason:
no_distance,beyond_truncation,inside_left. It shows whether truncation trimmed a tail or removed most of the survey.
Details
Distances are either exact (one distance per detection) or binned
(an interval distbegin to distend per detection, as recorded by strip
or band surveys). The two are fitted with different likelihoods.
How it works
The steps run in this order. The first refusal stops the function with an error.
Check the arguments.
datamust be a data frame.truncationmust be one positive finite number.left, if given, must be one non-negative finite number smaller thantruncation.Check the distance columns. Any of
distance,distbeginanddistendthat is present must be numeric (an all-NAcolumn is allowed) and must not be negative.Decide the distance type. Refuse a table with no distances, and refuse a table with both exact and binned distances.
Check
distance_source, if present, on the rows with an exactdistance. Refuse"break_off"distances. Warn about"circling"distances. Only rows that will be fitted (withinlefttotruncation) are counted.Count, by reason, the rows that will be dropped: no distance, beyond
truncation, or insideleft.For binned data:
Drop rows with a missing
distbeginordistend.Refuse any
distendofInf.Drop bins that end beyond
truncationor begin insideleft.Refuse if no rows remain.
Derive
breaksfrom the bins, refusing bins that do not tile; or, ifbreaksis supplied, check that it contains every recorded bin edge.Refuse if the highest break is not
truncation.Refuse if the lowest break is not
left(or 0 whenleftisNULL).Remove the
distancecolumn.
For exact data:
Warn that
breaksis ignored, if it was supplied.Remove the
distbeginanddistendcolumns.Drop rows with no distance, beyond
truncation, or insideleft.Refuse if no rows remain.
Add an
objectcolumn numbering the rows if there is none. Refuse duplicatedobjectvalues.
Rows with no distance are how a flatfile records a sample with no detections, so dropping them is expected. Every dropped row is counted in the return value.
What it refuses and why
| Condition | Reason |
| Non-numeric distances | Text or factor codes would be compared to truncation as text or level numbers, keeping the wrong rows. |
| Negative distances | A perpendicular distance has no side. Use abs() if the sign records the side of the line. |
| Exact and binned distances together | The two likelihoods differ, so their AICs cannot be compared in one sweep. Split the table on its distance-source column and sweep each part. |
distance_source == "break_off" | A break-off distance runs from where the aircraft left the line to the logged position. It is not perpendicular to the line. |
distend of Inf | An open top bin cannot be fitted. Drop those rows or close the bin. This applies even if truncation would drop the bin. |
Bins that do not tile (derived breaks) | If bins leave gaps or overlap, they do not define one set of cutpoints. |
breaks missing a recorded bin edge | Goodness of fit is computed over breaks, so breaks must be the survey's own cutpoints. |
Highest break not equal to truncation | A binned fit integrates over the bins. A gap between the top bin and truncation is effort with no bin. |
Lowest break not equal to left (or 0) | The same gap at the near end. It occurs when the innermost bin had no detections, or when left falls inside a bin. Supply breaks to fix it. |
| No rows left after truncation | There is nothing to fit. |
Duplicated object | mrds identifies detections by object. |
What it warns about
distance_source == "circling": the animal's position while the aircraft circled, projected onto the line. It is a perpendicular distance, but measured minutes after the detection.distsamp::detection_data()excludes these rows unlessinclude_circling = TRUE. They are kept, and the warning gives their count.breakssupplied with exact distances: it is ignored.
Examples
d <- data.frame(object = 1:5, distance = c(10, 50, 120, NA, 900))
prep <- prepare_distance_data(d, truncation = 400)
prep$n_dropped
#> [1] 2
prep$dropped
#> no_distance beyond_truncation inside_left
#> 1 1 0
prep$data
#> object distance
#> 1 1 10
#> 2 2 50
#> 3 3 120