
List the Starting-Value Order of a Distance-Removal Model
Source:R/gdr_start_values.R
gdr_start_values.RdRead the fitted coefficient and log SD values of an unmarked
distance-removal (GDR) model in the order that unmarked::gdistremoval()
expects for its starts argument, with a map that names the model
component and position of each value. Use it to build extra starting
values for make_gdr_refitter() and fit_gdr_response_field().
Arguments
- model
An
unmarkedFitGDRfitted byunmarked::gdistremoval()withunmarked1.5.2, using the C or TMB engine. Its stored estimates and optimizer values must be complete and agree with each other. Models withoffset()terms and zero-inflated TMB models are not supported. Finite values do not show that the model converged.
Value
A plain list:
starts: an unnamed numeric vector of the fitted values in starting order, on the link scales (log, logit, and log for SDs). Random-effect values are not included.map: a data frame with one row per element ofstarts:constructor_position, the TMB parameterblock(such as"beta_lambda"or"lsigma_lambda"),within_block(position in the block),fitted_position(position in the fitted optimizer vector),component("lambda","dist","rem"and so on),kind("regression"or"log_sd") andlabel, the coefficient or variance name stored byunmarked. For a TMB-engine model, pasteblockandwithin_blockas"beta_lambda[1]"to name a start formake_gdr_refitter().fitted_values: the fitted optimizer vector with its own names and order.coordinate_countis its length, not a count for AIC.random_modes_omittedgives the number of random-effect values left out in each component.optimizer: the stored objectivevalueandconvergencecode, as reported by the fit.provider: theunmarkedversion, the engine and, for TMB, the TMB version.format_versionidentifies the layout of this list.fingerprint: a SHA-256 of this list. It does not identify the data, settings or likelihood.fit_eligibility_established,likelihood_evaluatedanduncertainty_evaluated: alwaysFALSE. The function only reads stored values.
Why the order matters
With the TMB engine, the order of the starts argument can differ from
the order of the fitted optimizer vector. For example, unmarked may
place the negative binomial dispersion after the regression and variance
blocks in the starts, but next to abundance in the fitted vector. Repeated
coefficient labels cannot resolve this, so the map identifies each value
by its block and position and checks every value against the stored
estimates.
What the function does not do
It reads stored values only. It does not evaluate the likelihood, its gradient or Hessian, and it leaves the model unchanged. A failed or nonconverged fit can still have finite values, and its stored diagnostics keep their meaning. Nonfinite or inconsistent values stop with an error rather than being dropped or repaired.
The list can be saved with saveRDS() without saving a fitted model. It
cannot restore a fit. Refitting still needs the original data,
transformations, formulas and optimizer settings.
Examples
frame <- unmarked::unmarkedFrameGDR(matrix(c(0, 0, 1, 0), 2, byrow = TRUE),
matrix(c(0, 0, 0, 1, 0, 0), 2, byrow = TRUE),
dist.breaks = c(0, 25, 75), unitsIn = "m", period.lengths = c(1, 2, 1))
# A fixed point for inspecting coordinates, not a converged fit.
point <- unmarked::gdistremoval(data = frame, engine = "C", K = 30,
starts = c(log(8), log(40), qlogis(.3)), se = FALSE,
control = list(maxit = 0))
snapshot <- gdr_start_values(point)
# Log density, log distance scale and logit removal, in starting order
snapshot$starts
#> [1] 2.0794415 3.6888795 -0.8472979
# Component, block position and stored label of each value
snapshot$map[, c("block", "within_block", "component", "kind", "label")]
#> block within_block component kind label
#> 1 beta_lambda 1 lambda regression (Intercept)
#> 2 beta_dist 1 dist regression (Intercept)
#> 3 beta_rem 1 rem regression (Intercept)