Skip to contents

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.

Usage

g0(...)

Arguments

...

One or more data frames of components, each with columns key (character, or NA to apply to every key), component (name, such as "availability"), value (probability in (0, 1]) and se (standard error, finite and not negative), and optionally source (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 combined g(0)), se and cv. If no component is keyed there is one row with key = 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 NA standard error is an error. The CV of g(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%.

  1. Each component table is checked for the columns key, component, value and se, and at least one row. A missing source column is filled with NA.

  2. The tables are stacked. Every row must have a component name, a standard error, and a value in (0, 1].

  3. Keys are checked (see below).

  4. A warning is given for each of "availability" and "perception" that is absent.

  5. For each key, the matching rows are multiplied to give value, and \(CV = \sqrt{\sum (se/value)^2}\) gives cv; se is value * 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.