Combines the separately measured components of g(0) (availability,
perception, and any others), multiplies them per key, and propagates their
standard errors. Use it to hand a documented correction to the abundance
step; dsfit does not apply the correction itself.
Arguments
- ...
One or more data frames of components, each with columns
key(character, orNAto apply to every key),component(name, such as"availability"),value(probability in (0, 1]) andse(standard error, finite and not negative), and optionallysource(character).availability()returns this shape.
Value
An object of class dsfit_g0: a list with
- table
A tibble with one row per key:
key,value(the combinedg(0)),seandcv. If no component is keyed there is one row withkey = NA.- components
A tibble of the input rows (
key,component,value,se,source), kept so the correction can be taken apart again.
Why the result is an object
dsfit fits detection functions and does not compute abundance. The
correction is applied where density is calculated, outside this package.
A dsfit_g0 object records which components went in, where each came
from, and its standard error, so that what reaches the abundance step is
not a bare number of unknown origin.
Rules enforced
These follow docs/01-plan.md.
- No silent default of 1
At least one component is required. A missing
"availability"or"perception"component is named in a warning and in the printout. Assuming a component is 1 while believing it was corrected for biases abundance by a factor.- A standard error is required
A component with an
NAstandard error is an error. The CV ofg(0)often dominates the CV of abundance, so leaving it out understates the uncertainty.- Components are kept separate
Availability, perception and the geometric blind spot are measured in different ways. Each is kept as its own rows, so it stays visible which have been applied.
How it works
Components are assumed independent, because they come from separate studies (dive data for availability, double-observer trials for perception). Under independence the delta method gives the coefficient of variation (CV) of the product as
$$CV(g_0)^2 = \sum_i CV(x_i)^2$$
so the least precise component sets the floor: a perception CV of 30% cannot be offset by an availability CV of 2%.
Each component table is checked for the columns
key,component,valueandse, and at least one row. A missingsourcecolumn is filled withNA.The tables are stacked. Every row must have a component name, a standard error, and a value in (0, 1].
Keys are checked (see below).
A warning is given for each of
"availability"and"perception"that is absent.For each key, the matching rows are multiplied to give
value, and \(CV = \sqrt{\sum (se/value)^2}\) givescv;seisvalue * cv.
Keys
Components are matched on key (for example a month). A component given as
a single row with key = NA applies to every key, such as one perception
estimate combined with monthly availability. Otherwise each component must
have exactly one row for each key in the full set of keys.
Components keyed on different things are refused, not joined. Availability by month and perception by year have no correct join: the answer needs one value per month-year, so build that cross product and key both components on it. Also refused: several rows with no keys, a mix of keyed and unkeyed rows, and duplicate keys within a component.
Recording where a component came from
A component may carry a source column, which is kept in the object and
printed. A component without one is printed as source not recorded.
This matters most for perception. Estimating it needs two independent observer teams, and whether a programme ran them varies by programme, not by the archive (such as NARWC) that holds its data. Perception is often borrowed from another programme. Roberts et al. (2024) estimated it only from NOAA's AMAPPS surveys, applied it to data from ten other institutions, and noted this could bias their density estimates. Recording the source keeps a borrowed correction from looking local.
References
Laake, J.L. and Borchers, D.L. (2004) Methods for incomplete detection at distance zero. In Advanced Distance Sampling, pp. 108-189. Oxford University Press. Why the components are separate quantities.
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. doi:10.3354/meps14547 Perception borrowed across programmes.
See also
availability() for the availability component, sweep_models()
for the detection function fit, which this does not enter.
Examples
avail <- availability(surface = 60, dive = 240, window = 24,
se_surface = 8, se_dive = 25)
avail$source <- "focal follows, this survey"
# A perception estimate borrowed from another programme, recorded as such
perception <- data.frame(
key = NA_character_, 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 focal follows, this survey
#> perception AMAPPS double-observer, borrowed - not measured on this survey
#>
#> key g0 se cv
#> - 0.1878 0.032 0.171
#>
#> Divide abundance by g0, and propagate cv. This package does not
#> apply it: correction happens at the abundance step.
# Without perception: a warning, and "assumed 1" in the printout
suppressWarnings(g0(avail))
#> <dsfit_g0>
#> assumed 1: perception
#> components:
#> availability focal follows, this survey
#>
#> key g0 se cv
#> - 0.2761 0.0297 0.108
#>
#> Divide abundance by g0, and propagate cv. This package does not
#> apply it: correction happens at the abundance step.