check_drm() runs a compact set of model-fit diagnostics. It is intended as
a first-pass guardrail before interpreting distributional models, especially
fits with random effects, known sampling covariance, phylogenetic location
effects, or bivariate residual correlation rho12.
Usage
check_drm(object, ...)
# S3 method for class 'drmTMB'
check_drm(
object,
gradient_tolerance = 0.001,
rho_boundary = 0.98,
sd_boundary = 1e-04,
...
)Arguments
- object
A
drmTMBfit.- ...
Reserved for future diagnostic options.
- gradient_tolerance
Maximum absolute fixed-parameter gradient treated as acceptable.
- rho_boundary
Absolute residual or structured correlation value above which a bivariate Gaussian fit receives a warning.
- sd_boundary
Random-effect standard deviation below which a fit receives a warning that the variance component is near the lower boundary.
Value
A data frame of checks with columns check, status, value, and
message. The returned object has class drm_check.
Details
The current checks cover optimizer convergence, finite objective values,
optimizer evaluation counts, fixed-parameter gradients including the largest
gradient component label, whether
TMB::sdreport() was computed, skipped, or failed, Hessian status from
TMB::sdreport(), finite fixed-effect standard errors, dropped rows,
positive scale parameters, random-effect standard deviations near the lower
boundary, bivariate residual-correlation rho12 values near the boundary,
Student-t nu boundary behaviour, known sampling covariance summaries,
dense known-covariance storage scale, dense fixed-effect design size and
density, random-effect replication, and random-slope design variation. If a
univariate Gaussian fit includes one or more matched labelled
mu/sigma random-intercept covariance blocks, check_drm() also reports
group replication and whether either component is tiny relative to its
interpretation scale for each independent block. If a bivariate Gaussian fit
includes a matched
labelled mu1/mu2 random-intercept covariance block, check_drm() reports
group replication and whether either group-level SD is tiny relative to the
matching residual scale. For a matched labelled sigma1/sigma2 block, it
reports group replication and whether either log-sigma random-effect SD is
tiny. If a bivariate Gaussian fit includes an ordinary all-four q=4
mu1/mu2/sigma1/sigma2 block, it reports group replication, location
SDs relative to residual scales, log-sigma SDs, and whether any latent
correlation is near the boundary. If a bivariate Gaussian fit includes
matching mu1/mu2 phylogenetic location effects, check_drm() also reports
whether the fitted phylogenetic mean-mean correlation is near the boundary,
whether either phylogenetic SD is tiny relative to the matching residual
scale, and whether an ordinary group-level covariance block uses the same
grouping factor. If a bivariate Gaussian fit includes a phylogenetic q=4
mu1/mu2/sigma1/sigma2 block, it reports species replication,
location SDs relative to residual scales, log-sigma SDs, and whether any
latent phylogenetic correlation is near the boundary. If a univariate
Gaussian fit includes spatial(1 | site, coords = coords) in mu, it
reports site replication, fitted coordinate range, the spatial SD, and
whether the spatial SD is tiny relative to the residual scale. If a Gaussian
fit includes sd_phylo(species) ~ x_species,
sd_phylo1(species) ~ x_species, or
sd_phylo2(species) ~ x_species, it reports species replication and the
fitted direct-SD surface range. If a univariate Gaussian fit used
drm_control(aggregate_gaussian = TRUE), it reports original rows,
aggregation cells, compression ratio, and largest cell size. If a fit was
stored with
drm_control(keep_tmb_object = FALSE), the
fixed-gradient check is reported as a note because the TMB
automatic-differentiation object is not available. If a fit used
drm_control(se = FALSE), the sdreport_status, Hessian, and
finite-standard-error checks are reported as notes. If sdreport() was
requested but failed, those rows are warnings.
Use check_drm() before interpreting coefficients, fitted values, or
response-scale quantities. A note records something to inspect, such as
dropped rows or a singly observed random-effect level. A warning means the
fitted model may still be useful but needs inspection before inference. An
error means at least one basic diagnostic failed. For programmatic checks,
the returned object has attr(x, "ok") == TRUE only when no rows have
warning or error status.
Examples
set.seed(1)
dat <- data.frame(y = rnorm(40), x = rnorm(40))
fit <- drmTMB(drm_formula(y ~ x, sigma ~ x), data = dat)
check_drm(fit)
#> <drm_check: 10 checks>
#> ok: 10; notes: 0; warnings: 0; errors: 0
#> check status
#> optimizer_convergence ok
#> optimizer_budget ok
#> finite_objective ok
#> fixed_gradient ok
#> sdreport_status ok
#> hessian_positive_definite ok
#> standard_errors_finite ok
#> dropped_rows ok
#> positive_scale ok
#> fixed_effect_design_size ok
#> value
#> 0
#> iterations=9; function=18; gradient=9
#> 50.32
#> max=0.0001709; component=beta_mu[1]
#> ok
#> TRUE
#> range=[0.1129,0.1491]
#> nobs=40; dropped=0
#> min=0.7849
#> total_mb=0.007614; max_cols=2; largest=mu; largest_class=matrix; largest_density=1.000
#> message
#> nlminb convergence code is 0.
#> Optimizer evaluation counts recorded; no eval.max or iter.max control was supplied.
#> Objective and log-likelihood are finite.
#> Maximum absolute fixed gradient is <= 0.001; largest component is beta_mu[1].
#> TMB::sdreport() completed successfully.
#> sdreport reports a positive-definite Hessian.
#> All fixed-effect standard errors are finite.
#> No rows were dropped by model-frame or known-covariance filtering.
#> All fitted scale values are finite and positive.
#> Dense fixed-effect design matrices are modest for this fit.