Diagnose a fitted detection function

Reports whether a fitted detection function is well conditioned enough to trust its covariance matrix. This matters because pDetInArea() propagates detection function uncertainty by drawing coefficients from MASS::mvrnorm(coef(detFun), vcov(detFun)). If vcov is unreliable, the reported CV.pa is unreliable with it.

Usage

checkDetFun(
  detFun,
  trueParams = NULL,
  kappaMax = 1e+08,
  seRatioMax = 100,
  coefMax = 10,
  verbose = TRUE
)

Arguments

detFun

A fitted detection function from fitDetFun().

trueParams

Optional data.frame of the parameters used to simulate the detectors, with columns location and scale, in the same order as the occasions. When supplied, a parameter recovery table is added comparing the fitted -intercept / slope against location and the fitted slope against 1 / scale. Simulation studies only.

kappaMax

Condition number above which vcov is flagged. Default 1e8.

seRatioMax

Ratio of largest to median standard error above which the fit is flagged. Default 100.

coefMax

Largest absolute coefficient above which the fit is flagged. Default 10.

verbose

Print a human readable report. Default TRUE.

Value

Invisibly, a list with elements modelType, nCoef, kappa, se, seRatio, maxAbsCoef, iter, ok, problems, and, when trueParams is supplied, recovery.

Details

VGAM::vglm() emits warnings freely during fitting. A posbernoulli.t fit with ten occasions will routinely produce a dozen checkwz messages and a half-step warning, and VGAM's "some quantities such as z, residuals, SEs may be inaccurate" text is emitted whenever IRLS damps its final step, without checking whether the SEs are in fact affected. Those warnings are usually benign. This function checks the things that actually indicate trouble.

What genuine separation looks like: one occasion's coefficient runs to double digits, its standard error blows up by orders of magnitude relative to the others, and the condition number of vcov climbs past about 1e8. What benign flooring looks like: a handful of working weights floored at high SNR where the fitted probability approaches one, coefficients of order unity, and standard errors within a factor of ten or so of each other.

Convergence warnings raised at fitting time cannot be recovered from the fitted object afterwards. For vglm fits the iteration count is reported instead: a fit that used every available iteration did not converge, whatever the warnings said. To capture the warnings themselves, wrap the fitDetFun() call in withCallingHandlers() at fit time.

Examples

if (FALSE) { # \dontrun{
fit <- fitDetFun(adj, modelType = "vglm", yColNames = oc,
                 whichObserver = "any")
checkDetFun(fit)
checkDetFun(fit, trueParams = detParams)
} # }