g(0) is the probability of detecting an animal that is directly on the trackline. Every detection function dsfit fits assumes g(0) = 1. If the true value is lower, every candidate model’s average detection probability is too high by the same factor. The AIC ranking does not change, so model selection cannot reveal the error.
This vignette is the reference for:
- availability, the one component of g(0) that dsfit computes;
- checking a dataset before a sweep, including what it can support;
- assembling a full g(0) correction from components, and recording where each came from.
Sections 2 and 3 use a small simulated survey, defined in Section 2.
1. Availability
Availability is the probability that an animal was at the surface,
and so could be seen, while the observers had its position in view.
availability() computes it from the mean surfacing
interval, the mean diving interval, and the time in view (the window).
The intervals below are from example_dive_intervals, which
is invented for demonstration.
availability(
surface = example_dive_intervals$surface, # mean surfacing interval, s
dive = example_dive_intervals$dive, # mean diving interval, s
window = view_window(radius = 300, speed = 50),
key = as.character(example_dive_intervals$month)
)
#> # A tibble: 6 × 4
#> key component value se
#> <chr> <chr> <dbl> <dbl>
#> 1 Dec availability 0.245 NA
#> 2 Jan availability 0.286 NA
#> 3 Feb availability 0.361 NA
#> 4 Mar availability 0.477 NA
#> 5 Apr availability 0.683 NA
#> 6 May availability 0.849 NAAvailability runs from 0.25 in December to 0.85 in May. One constant
value for the season would be wrong in most months. se is
NA because no standard errors were given for the intervals
(Section 1.5).
1.1 The equation
The formula is from Laake et al. (1997). With mean surfacing interval
E(s), mean diving interval E(d), and window
w:
E(s) + E(d) · (1 − exp(−w / E(d)))
a = ────────────────────────────────────
E(s) + E(d)
The term E(d) · (1 − exp(−w / E(d))) is the added chance
that an animal underwater when the window opens surfaces before it
closes. Two limits follow, and both are checked by the package
tests:
- As
w → 0(an instantaneous look),a = E(s) / (E(s) + E(d)), the proportion of time spent at the surface. - As
w → ∞,a → 1, because every animal surfaces eventually.
A longer window, from a slower platform or a wider field of view, therefore raises availability.
1.2 The time-in-view window
The window depends on the platform’s field of view. dsfit provides two geometric models.
view_window_aerial() is for an aircraft. The observer’s
field of view is a wedge running forward and aft of the aircraft. An
animal farther from the trackline stays in the wedge longer, so the
window increases with perpendicular distance x:
t(x) = α + 2 · x · tan(θ) / v
where α is the time in view at the trackline, θ is the viewing angle forward and aft of perpendicular, and v is ground speed. Ganley et al. (2019) calibrated this for their aircraft by timing a navigation buoy through the field of view: 51.22 s at the trackline, increasing by about 0.03 s per metre of perpendicular distance.
view_window() is for a circular viewing area of radius r
crossed along a chord:
w(x) = 2 · sqrt(r² − x²) / v
This window decreases with distance and is zero at the edge of view. Using it for an aircraft reverses the direction of the distance effect. Both are approximations. A measured window, like Ganley et al.’s, is better than either.
The examples in this vignette use view_window() with
invented intervals, so they demonstrate the functions rather than any
real platform.
1.3 Why availability is computed, not estimated
An animal underwater while the platform passes is missed at every perpendicular distance equally. Availability therefore scales g(x) by a constant and does not change the shape of the distance distribution. The distances contain no information about it.
The inputs come from outside the survey being corrected: dive intervals from focal follows, tagging or drone work, and the window from the platform. Each has its own uncertainty, which is carried into the result (Section 1.5).
1.4 Why availability varies
Ganley et al. (2019) measured availability for right whales in Cape Cod Bay from focal follows and the aircraft’s field of view. It ranged from 0.27 in January to 0.91 in April, following the depth of the copepods the whales feed on. Roberts et al. (2024) applied separate perception and availability corrections per platform, team and conditions across 11 institutions.
A single fixed value is therefore a risky input. For example, if availability is about 0.5 in a month and perception about 0.7, g(0) is about 0.35. Using a fixed 0.83 instead understates the correction by more than a factor of two, and model selection cannot reveal the error.
1.5 The output and its standard error
availability() returns a table with columns
key, component, value and
se. This is the format g0() takes, so
availability and perception rows can be stacked.
Availability is a fixed function of its inputs, so its uncertainty
comes from them. Pass se_surface and se_dive
and the standard errors are propagated by the delta method.
- Passing only one of them is an error, because propagating one and dropping the other would understate the standard error.
- Passing neither gives
se = NA. A made-up precision is not supplied.
If the raw focal-follow data are available, bootstrapping them is better than the delta method, because it does not assume the interval means are jointly normal. Ganley et al. (2019) bootstrapped.
1.6 The bundled datasets
| dataset | source | contents |
|---|---|---|
ganley_availability |
Ganley et al. (2019), Table S1 | mean dive and surface intervals, percent surface time and availability by month, from 86 focal follows in Cape Cod Bay |
ganley_detection |
Ganley et al. (2019), Table S2 | 20 years of annual detection-function results from one programme and aircraft |
example_dive_intervals |
invented | intervals with standard errors, to demonstrate the functions |
ganley_availability:
| month | % surface | dive (s) | surface (s) | availability |
|---|---|---|---|---|
| Jan | 16 | 533 | 48 | 0.27 |
| Feb | 34 | 256 | 226 | 0.52 |
| Mar | 31 | 219 | 67 | 0.52 |
| Apr | 55 | 88 | 801 | 0.91 |
ganley_detection has p between 0.431 and
0.866. Its p, p_se and cvm_p
columns match those in selection_table(). Its
p is the average detection probability, not perception
bias. Ganley et al. did not estimate perception, which needs a second
observer team.
Three points about Table S1 that are easy to get wrong:
-
percent_surface_timeis notE(s) / (E(s) + E(d)). For January the intervals give 48 / (48 + 533) = 8.3%, but the table lists 16%. For April they give 90% against 55%. The percentage is a mean of per-follow percentages, while the intervals are means of intervals, and the two need not agree. A package test checks that they do not. - The
availabilityvalues are bootstrap medians and were not computed at a common window.availability()will not reproduce them. - The
availability_variancecolumn is ambiguous. Read as a variance, January’s standard error is √0.04 = 0.2, a CV of 74%. Read as a standard error, the CV is 15%. Neither matches the error bars in the paper’s figure. The column is kept as published, and you must decide how to use it before passing it tog0().
2. Checking data before a sweep
diagnose_sweep() runs the checks that
sweep_models() runs before fitting: the data checks,
truncation, and model-set expansion. It never calls
mrds::ddf().
The simulated survey has 300 detections from a half-normal detection function whose scale decreases with Beaufort sea state, plus 20 rows with no distance. Rows with no distance record samples with no detections.
set.seed(1)
n <- 300
detections <- data.frame(
object = 1:n,
beaufort = sample(0:4, n, replace = TRUE)
)
detections$distance <- abs(rnorm(n, 0, 900 - 90 * detections$beaufort))
detections <- rbind(detections,
data.frame(object = n + 1:20, beaufort = NA, distance = NA))
diagnose_sweep(detections, model_set(c("hn", "hr")), truncation = 2500)
#> dsfit sweep diagnosis
#>
#> == Toolchain ==
#> ok mrds 3.0.1 is installed
#>
#> == Data ==
#> ok 320 rows, 300 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 299 of 320 rows kept at truncation 2500
#> dropped: 20 with no distance, 1 beyond the truncation
#> ok 299 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.It reports problems that would otherwise appear as an error from
inside mrds, or not at all:
- a covariate formula naming a column that is not in the data;
- a truncation that drops most of the data, which usually means a units mismatch;
- a covariate that is constant or has missing values;
- a model set that handles the blind spot twice (gamma key with
left).
Missing structure, such as having only one observer team, is reported
as a note, not a warning. A single-observer survey is not
misconfigured, and warning on every such dataset would hide the real
problems.
The blind-spot check asks two questions. First, is the gap between the trackline and the nearest detection wide compared with the truncation distance? Second, does the number of detections start abruptly at the edge of the gap, or rise gradually? An abrupt start indicates a hard cutoff, which no key function can fit, including gamma; left truncation is then the right treatment. A gradual rise is the shape the gamma key is for.
3. What the data can support
detection_structure() reports which analyses a table of
detections supports, before anything is fitted.
detection_structure(detections)
#> <dsfit_structure>
#> 320 rows, 300 exact distances
#> nearest detection at 3.167 - a blind spot beneath the platform would show here
#>
#> can:
#> fit a detection function 300 exact distances; at or above the 60-80 usually suggested
#> test fit with Cramer-von Mises exact distances have an empirical distribution to test
#> test fit with chi-square over cutpoints mrds chooses, which makes it the weaker test here
#> fit covariate models candidates: beaufort; recorded as survey conditions: beaufort
#>
#> cannot:
#> estimate perception bias no double-observer structure: no `observer` or `detected` column. Perception needs two independent teams and cannot be recovered from a single-observer survey at any sample size
#> estimate availability not estimable from distances by construction: a submerged animal is missed at every distance equally. Compute it from dive data with availability()
#> carry group size to abundance no `size` column; abundance would count groups, not individuals
#>
#> Structure only. That something is supported is not a reason to do it.Whether perception bias can be estimated depends on whether the survey programme ran two independent observer teams. The data do not announce this, and a pooled archive extract may or may not keep the structure. Fitting a single-observer dataset and reporting it as if perception had been corrected gives a number that is wrong by a factor.
Each analysis is reported as supported, not supported, or
partly. partly covers incomplete
double-observer structure, for example an observer column
with no detected column, which looks like double-observer
data but is not.
detection_structure() only reports.
prepare_distance_data(), which sweep_models()
calls, enforces the checks with errors.
4. Assembling a g(0) correction
g0() combines the components by multiplying them and
propagates their standard errors.
avail <- availability(
surface = example_dive_intervals$surface,
dive = example_dive_intervals$dive,
window = view_window(radius = 300, speed = 50),
se_surface = example_dive_intervals$se_surface,
se_dive = example_dive_intervals$se_dive,
key = as.character(example_dive_intervals$month)
)
avail$source <- "example intervals - invented"
perception <- data.frame(
key = NA, component = "perception", value = 0.68, se = 0.09,
source = "AMAPPS double-observer, borrowed - not measured on this survey"
)
g0(avail, perception)
#> <dsfit_g0>
#> components:
#> availability example intervals - invented
#> perception AMAPPS double-observer, borrowed - not measured on this survey
#>
#> key g0 se cv
#> Dec 0.1666 0.0344 0.206
#> Jan 0.1946 0.0390 0.201
#> Feb 0.2457 0.0462 0.188
#> Mar 0.3242 0.0558 0.172
#> Apr 0.4645 0.0696 0.150
#> May 0.5776 0.0799 0.138
#>
#> Divide abundance by g0, and propagate cv. This package does not
#> apply it: correction happens at the abundance step.The perception row has key = NA, so it applies to every
month.
g0() returns an object; it does not apply the
correction. dsfit fits detection functions and does not compute
abundance. The correction is applied where abundance is calculated.
g0() enforces these rules:
-
No silent default of 1. A missing component is named in a warning when the object is built, and every time it prints:
g0(avail) #> <dsfit_g0> #> assumed 1: perception #> components: #> availability example intervals - invented #> #> key g0 se cv #> Dec 0.2450 0.0388 0.158 #> Jan 0.2861 0.0431 0.151 #> Feb 0.3613 0.0483 0.134 #> Mar 0.4767 0.0525 0.110 #> Apr 0.6831 0.0481 0.070 #> May 0.8494 0.0339 0.040 #> #> Divide abundance by g0, and propagate cv. This package does not #> apply it: correction happens at the abundance step. Every component needs a standard error. A component with
se = NAis an error. Together withavailability()returningNArather than inventing a standard error, this means a correction never carries an unstated precision.Every component needs a name in the
componentcolumn, so it is clear which have been applied.All keyed components must have the same keys. Components keyed on different things are rejected. For example, availability by month and perception by year cannot be joined. Key both on month-year instead.
4.1 Recording where a component came from
Each component can have a source column. It is most
useful for perception.
Estimating perception needs two independent observer teams. Many survey programmes did not run them, so the only available perception estimate is often borrowed from another programme. Roberts et al. (2024) did this: perception was estimable only from NOAA’s AMAPPS surveys, and they applied those estimates to data from the other ten institutions, noting that this may have biased their density estimates.
source is printed with every g0() result,
as in the output above. A component without one is shown as
source not recorded:
avail$source <- NULL
g0(avail)
#> <dsfit_g0>
#> assumed 1: perception
#> components:
#> availability source not recorded
#>
#> key g0 se cv
#> Dec 0.2450 0.0388 0.158
#> Jan 0.2861 0.0431 0.151
#> Feb 0.3613 0.0483 0.134
#> Mar 0.4767 0.0525 0.110
#> Apr 0.6831 0.0481 0.070
#> May 0.8494 0.0339 0.040
#>
#> Divide abundance by g0, and propagate cv. This package does not
#> apply it: correction happens at the abundance step.4.2 How the CVs combine
The components are assumed independent and are multiplied, so their squared coefficients of variation (CV, standard error divided by estimate) add:
CV(g0)² = Σ CV(xᵢ)²
The least precise component therefore sets the minimum CV. A
perception estimate with a 30% CV keeps the CV of g(0) at 30% or more,
however precise availability is. In the
g0(avail, perception) output above, perception alone
contributes a CV of 0.09 / 0.68 = 0.13, and the cv column
never falls below it.
References
Ganley, L.C., Brault, S. and Mayo, C.A. (2019) What we see is not what there is: estimating North Atlantic right whale Eubalaena glacialis local abundance. Endangered Species Research 38:101-113. https://doi.org/10.3354/esr00938
Laake, J.L., Calambokidis, J., Osmek, S.D. and Rugh, D.J. (1997) Probability of detecting harbor porpoise from aerial surveys: estimating g(0). The Journal of Wildlife Management 61:63-75. https://doi.org/10.2307/3802415
Roberts, J.J., Yack, T.M., Fujioka, E., Halpin, P.N., Baumgartner, M.F. and others (2024) North Atlantic right whale density surface model for the US Atlantic evaluated with passive acoustic monitoring. Marine Ecology Progress Series 732:167-192. https://doi.org/10.3354/meps14547