Expands key functions, adjustment series and covariate formulas into a grid
of candidate models, one row per candidate. Pass the result to
sweep_models() to fit them all.
Usage
model_set(key = c("hn", "hr"), adjustment = NULL, order = NULL, formula = ~1)Arguments
- key
Character vector of key functions: any of
"hn","hr","unif","gamma". Defaultc("hn", "hr").- adjustment
Character vector of adjustment series:
"cos"(cosine),"herm"(Hermite polynomial) or"poly"(simple polynomial). One candidate per series.NULL(default) fits no adjustment terms.- order
Integer vector of highest adjustment orders, one candidate per element. Orders are cumulative, as in
Distance::ds(): a candidate carries every term of its series up toorder. For example,order = 3on"hn"with"cos"fitsadj.order = c(2, 3). Cosine orders run 2, 3, 4, ... (1, 2, 3, ... for"unif"). Hermite and polynomial orders run 4, 6, 8, ... (2, 4, 6, ... for"unif").NULL(default) gives the first term of the series only. An order outside its series is dropped with a warning. Ignored whenadjustmentisNULL.- formula
One-sided formula, or a list of them, giving detection covariates.
~1(default) means no covariates and fits withcds; any other formula fits withmcds.
Value
A tibble with one row per candidate and columns:
model_idLabel, e.g.
"hn","hr+cos(2,3)","hn wt_beaufort".keyKey function.
adjustmentAdjustment series, or
NA.orderHighest adjustment order, or
NA.formulaCovariate formula as a string.
dsmodelThe model formula string passed to
mrds::ddf().
How it works
Checks that every key, adjustment series, order and formula is valid.
Crosses keys, series, orders and formulas into a grid.
Drops, with a warning, candidates that cannot be fitted meaningfully: a uniform key with no adjustment, a uniform key with covariates, and an adjustment order outside its series.
Builds each candidate's
mrdsmodel string and itsmodel_idlabel.Drops, with a warning, duplicate candidates.
Key functions
"hn"Half-normal. A shoulder at zero and a smooth fall-off. The usual default.
"hr"Hazard-rate. A broader shoulder and a heavier tail, with a second parameter.
"unif"Uniform. Detection is certain out to the truncation distance, which is a strip transect. It is kept only with adjustment terms. It takes no covariates, because it has no scale parameter for them to act on.
"gamma"Gamma. Unimodal, with its peak away from zero, so detection is lowest on the track-line.
mrdsscales it to 1 at its peak, not at zero. Not available inDistance::ds().
Gamma key and left truncation
An aircraft cannot see the water directly beneath it, and a ship cannot see
past its bow wave. For such a platform the gamma key fits the near distances
better than a half-normal, which must peak at zero. Left truncation models
the same blind spot by discarding the near distances. Use one or the other,
not both. sweep_models() takes left and warns if it is set for a model
set that contains the gamma key.
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.
Laake, J.L. and Borchers, D.L. (2004) Methods for incomplete detection at distance zero. In Advanced Distance Sampling, Oxford University Press.
Becker, E.A. and Quang, P.X. (2009) A gamma-shaped detection function for line-transect surveys with mark-recapture and covariate data. Journal of Agricultural, Biological and Environmental Statistics 14:207-223. doi:10.1198/jabes.2009.0013 Source of the gamma key, developed for aerial surveys.
Examples
# Default: half-normal and hazard-rate, no adjustments or covariates
model_set()
#> # A tibble: 2 × 6
#> model_id key adjustment order formula dsmodel
#> <chr> <chr> <chr> <int> <chr> <chr>
#> 1 hn hn NA NA ~1 "~cds(key = \"hn\", formula = ~1)"
#> 2 hr hr NA NA ~1 "~cds(key = \"hr\", formula = ~1)"
# Cosine adjustments up to orders 2 and 3
model_set(key = c("hn", "hr"), adjustment = "cos", order = 2:3)
#> # A tibble: 4 × 6
#> model_id key adjustment order formula dsmodel
#> <chr> <chr> <chr> <int> <chr> <chr>
#> 1 hn+cos(2) hn cos 2 ~1 "~cds(key = \"hn\", formula = ~1, …
#> 2 hr+cos(2) hr cos 2 ~1 "~cds(key = \"hr\", formula = ~1, …
#> 3 hn+cos(2,3) hn cos 3 ~1 "~cds(key = \"hn\", formula = ~1, …
#> 4 hr+cos(2,3) hr cos 3 ~1 "~cds(key = \"hr\", formula = ~1, …
# With and without a detection covariate
model_set(key = "hn", formula = list(~1, ~wt_beaufort))
#> # A tibble: 2 × 6
#> model_id key adjustment order formula dsmodel
#> <chr> <chr> <chr> <int> <chr> <chr>
#> 1 hn hn NA NA ~1 "~cds(key = \"hn\", formul…
#> 2 hn wt_beaufort hn NA NA ~wt_beaufort "~mcds(key = \"hn\", formu…
# The gamma key, for a platform that cannot see beneath itself
model_set(key = c("hn", "gamma"))
#> # A tibble: 2 × 6
#> model_id key adjustment order formula dsmodel
#> <chr> <chr> <chr> <int> <chr> <chr>
#> 1 hn hn NA NA ~1 "~cds(key = \"hn\", formula = ~1)"
#> 2 gamma gamma NA NA ~1 "~cds(key = \"gamma\", formula = ~1)"