Runs the checks a sweep would run, without calling mrds::ddf(), and prints
a report of problems found. Use it before sweep_models() to catch a
misconfiguration in seconds, instead of after a sweep that errors inside
mrds or returns a table that looks valid but is not.
Arguments
- data
Data frame, one row per detection, in the form
sweep_models()takes.- models
A
model_set(), orNULL(default) for the default set.- truncation
Number. Right truncation distance, in the units of the distances. Required, as for a sweep.
- left
Number or
NULL(default). Left truncation distance.- breaks
Numeric vector or
NULL(default). Bin cutpoints for binned data; derived from the bins whenNULL.
Value
Invisibly, a list with the results reached before any stop:
structureThe
detection_structure()result, orNULLif the data could not be read.preparedThe
prepare_distance_data()result, orNULLif it failed. Absent if the report stopped earlier.modelsThe model set checked. Absent if the report stopped earlier.
The report itself is printed to the console.
How it works
Each finding is printed as one line marked ok, note, WARN or FAIL.
A note is a fact about how the survey was flown (for example, a single
observer team); it does not count as a problem. WARN and FAIL lines
count as problems. A failure marked "stops" below ends the report early.
Refuse to run if
truncationis missing (an error, not a report line).Toolchain: check
mrdsis installed (WARNif not).Data: read the table with
detection_structure().FAILand stop if it cannot be read.FAILif it has no distances; otherwise report the count and type.WARNfor each pair of columns that name the same variable.WARNfor each analysis whose structure is incomplete (supportedisNA), such as a partial double-observer setup.noteif perception bias cannot be estimated or there is nosizecolumn.
Truncation: run
prepare_distance_data().Its warnings are printed as
WARNlines. Its errors are printed as aFAILline and stop the report.Report how many rows were kept, and how many were dropped for each reason.
WARNif truncation removes more than 50% of the rows that have a distance.
Sample size:
FAILbelow 40 detections after truncation,WARNbelow 60,okotherwise (Buckland et al. 2001).Model set: build the default
model_set()or check the one given.FAILand stop if that errors; otherwise list the candidates.Blind spot: see the section below.
Covariates:
FAILif a formula names a column not indata. OtherwiseWARNfor a covariate with only one value, and for one with missing values (mrds drops those rows).Print a reminder that g(0) = 1 is assumed unless corrected at the abundance step. g(0) is the detection probability on the trackline. An error in it scales every candidate equally, so no check here can detect it. See
g0().Print a final line: no problems found, or problems above.
The constant and missing-value covariate checks use the rows that will be fitted, after truncation, since mrds never sees the rest.
Blind-spot check
A blind spot is a strip next to the trackline where the platform cannot see, such as beneath an aircraft. It shows as no detections close to the line.
The check fires when the nearest detection in the input data is more than
2% of truncation from the line. Every dataset has a smallest distance, so
a nonzero nearest distance alone is not evidence of a blind spot. The 2%
threshold is a heuristic.
There are two treatments, and they are alternatives: left truncation
(left), or the gamma key, which models detection rising from zero at the
line. The check reports:
| Situation | Result |
Gamma key in the set and left set (blind spot or not) | WARN: the blind spot is counted twice. |
Blind spot, left set, no gamma key | ok |
| Blind spot, abrupt onset | WARN: a hard edge, which left removes and no key function fits, gamma included. |
| Blind spot, gradual onset, gamma key in set | ok |
| Blind spot, too few detections (under 40) to classify the onset, gamma key in set | note |
Blind spot, neither left nor gamma | WARN |
Abrupt onset means detections start at close to their peak rate just
beyond the empty strip. The range from the nearest detection to
truncation is cut into 20 equal bins. The onset is abrupt when the first
bin's count is more than 60% of the largest bin's count. A geometric edge
(a window frame, a hull) gives this shape. A gradual decline in
detectability toward the line instead gives a rising first few bins, which
is what the gamma key fits. The test needs at least 40 detections; with
fewer, the onset is not classed as abrupt.
References
Buckland, S.T., Anderson, D.R., Burnham, K.P., Laake, J.L., Borchers, D.L. and Thomas, L. (2001) Introduction to Distance Sampling. Oxford University Press. Source of the 40 and 60-80 detection guidelines and of trimming roughly the outer 5% of distances.
See also
detection_structure(), which reports what the data could
support in principle. sweep_models(), which this is meant to run
before.
Examples
set.seed(1)
d <- data.frame(
object = 1:300,
distance = c(abs(rnorm(295, 0, 800)), rep(NA, 5)),
beaufort = sample(0:4, 300, replace = TRUE)
)
diagnose_sweep(d, model_set(c("hn", "hr")), truncation = 2000)
#> dsfit sweep diagnosis
#>
#> == Toolchain ==
#> ok mrds 3.0.1 is installed
#>
#> == Data ==
#> ok 300 rows, 295 exact distances
#> note estimate perception bias: no double-observer structure: no `observer` or `detected` column
#> note carry group size to abundance: no `size` column; abundance would count groups, not individuals
#>
#> == Truncation ==
#> ok 293 of 300 rows kept at truncation 2000
#> dropped: 5 with no distance, 2 beyond the truncation
#> ok 293 detections is at or above the 60-80 usually suggested
#>
#> == Model set ==
#> ok 2 candidates: hn, hr
#>
#> == What is still assumed ==
#> g(0) = 1, unless a correction is applied at the abundance step.
#> Nothing here can detect a wrong one: it scales every candidate
#> equally, so the ranking looks untouched. See ?g0.
#>
#> No problems found. Nothing was fitted.