Summarize a fitted model

summary() returns a compact summary of fixed-effect estimates, response-scale distributional, scale, shape, random-effect SD, correlation, and fitted random-effect covariance quantities when they are present. The covariance component reports currently fitted registry-backed rows and fitted bivariate phylogenetic covariance rows, including q=2 mean-mean and q=4 endpoint rows where present. The derived component reports simple point-estimate variance ratios – total_variance_share for a Gaussian random-intercept mu component and phylo_total_variance_share for a phylogenetic mu component – when the ingredients are unambiguous. Both divide by the TOTAL variance (every mu random-effect variance plus the residual variance), which is a different denominator from the icc()/repeatability() accessors (focal component variance over that component plus the residual only); see ?heritability and docs/design/259-heritability-icc-repeatability.md for the distinction. Both rows are computed only for Gaussian fits with an identity-link mean, where the latent, expected-data, and observed-data scales of de Villemereuil, Schielzeth, Nakagawa & Morrissey (2016, Genetics 204:1281-1294) coincide, so there is no separate latent- or liability-scale value to distinguish. residual_variance is sigma^2 when sigma's fixed part reduces to a single log-link intercept; when sigma additionally carries an ordinary random intercept, or a phylogenetic random intercept with a unit-diagonal correlation (the default phylo(...) route), residual_variance is instead the marginal residual variance exp(2*b0 + 2*sum_k(omega_k^2)) – E[sigma^2], not the squared median exp(2*b0) – where omega_k are the working-scale (log-SD) standard deviations of those effects. A random slope on sigma, a structured sigma effect without a verified unit-diagonal correlation (measured on the rows the design uses), or a fit that carries a sigma random effect while the log(sigma) soft clamp bent the assembled predictor for at least one observation (clamp_limited; a clamp-active sigma ~ 1 fit still returns its constant clamped scale), has no closed-form marginal residual variance here and is refused (a residual_variance.message attribute on the empty result names the reason, and is also shown under the (empty) derived table when printed); see docs/design/275-repeatability-scale-and-residual-variance.md. Derived confidence intervals are marked as unavailable until a nonlinear interval method is implemented. The derived table's residual_sd column is sqrt(residual_variance) – i.e. sqrt(E[sigma^2]) = exp(b0 + sum_k(omega_k^2)) – and this is a DIFFERENT quantity from the sigma row in the parameters component, which is always the conditional/median scale exp(b0). The two coincide only when sigma carries no random effect; when it does, residual_sd is larger (e.g. 1.0144 vs a sigma row of 0.7599 on one fixture), and both are labelled scale = "response" because both genuinely are on the response scale – they are not alternative scales of the same quantity, they are two different quantities. When TMB::sdreport() succeeds, direct response-scale parameter rows also include delta-method standard errors; descriptive fitted ranges and derived variance ratios do not. Confidence intervals are opt-in: fast Wald intervals are available for fixed effects and direct response-scale parameter rows, and slower profile-likelihood intervals are available for selected direct profile targets. Profile summaries keep Wald intervals for fixed effects unless fixed-effect profile targets are selected. Interval-aware tables include conf.status so rows without intervals can say whether an interval was not requested, needs newdata, is ready but unselected, or is currently unavailable. Use summary(fit, conf.int = TRUE) for fixed-effect and direct parameter Wald confidence intervals, and use method = "profile" with ci_parm for direct response-scale targets such as sigma, rho12, or a random-effect SD. Correlation Wald intervals use the fitted TMB correlation-link scale, equivalent to a guarded Fisher z/atanh transform, before returning lower and upper bounds on the correlation scale.

Usage

# S3 method for class 'drmTMB'
summary(
  object,
  conf.int = FALSE,
  level = 0.95,
  method = c("wald", "profile"),
  ci_parm = NULL,
  trace = FALSE,
  profile_precision = c("default", "fast"),
  ...
)

Arguments

object: A drmTMB fit.
conf.int: Logical; include confidence intervals when TRUE.
level: Confidence level for intervals.
method: Interval method used when conf.int = TRUE: "wald" for fast direct intervals or "profile" for profile-likelihood intervals on selected direct targets. summary() does not run bootstrap intervals yet; use confint(..., method = "bootstrap") for the current direct-target bootstrap route.
ci_parm: Optional character or integer vector selecting confidence interval targets. For method = "wald" and method = "profile", targets use the profile_targets() namespace, such as "sigma", "rho12", "sd:mu:(1 | id)", or "cor:mu:cor((Intercept),x | id)". NULL selects all direct Wald-ready targets for Wald intervals and currently ready direct non-fixed targets for profile intervals. This keeps large profile runs focused on scale, variance-component, and correlation rows unless fixed-effect profile targets are requested explicitly.
trace: Logical; passed to TMB::tmbprofile() for profile intervals.
profile_precision: Profile-control shortcut used with method = "profile". "default" leaves TMB::tmbprofile() controls unchanged, while "fast" supplies ystep = 0.5 and ytol = 2 unless the caller supplies those controls in ....
...: Additional arguments passed to TMB::tmbprofile() when conf.int = TRUE and method = "profile".

Value

An object of class summary.drmTMB.

Examples

dat <- data.frame(y = c(0.2, 0.5, 1.1, 1.4), x = c(-1, 0, 1, 2))
fit <- drmTMB(bf(y ~ x, sigma ~ 1), data = dat)
summary(fit)
#> <summary.drmTMB>
#> estimator: ML
#>                    estimate  std_error
#> mu:(Intercept)     0.590000 0.03674235
#> mu:x               0.420000 0.03000000
#> sigma:(Intercept) -2.701839 0.35355327
#> Distributional, random-effect, scale, and correlation parameters:
#>                  component  dpar       term   estimate  std_error    scale
#> sigma distributional-scale sigma (constant) 0.06708204 0.02371707 response
#> logLik: 5.132
#> convergence: 0
summary(fit, conf.int = TRUE)
#> <summary.drmTMB>
#> estimator: ML
#> confidence intervals: wald, level = 0.95
#>                    estimate  std_error   conf.low  conf.high conf.level
#> mu:(Intercept)     0.590000 0.03674235  0.5179863  0.6620137       0.95
#> mu:x               0.420000 0.03000000  0.3612011  0.4787989       0.95
#> sigma:(Intercept) -2.701839 0.35355327 -3.3947906 -2.0088873       0.95
#>                   conf.method conf.status profile.boundary profile.message
#> mu:(Intercept)           wald        wald               NA            <NA>
#> mu:x                     wald        wald               NA            <NA>
#> sigma:(Intercept)        wald        wald               NA            <NA>
#> Distributional, random-effect, scale, and correlation parameters:
#>                  component  dpar       term   estimate  std_error    scale
#> sigma distributional-scale sigma (constant) 0.06708204 0.02371707 response
#>         conf.low conf.high conf.status
#> sigma 0.03354758 0.1341379        wald
#> logLik: 5.132
#> convergence: 0
summary(
  fit,
  conf.int = TRUE,
  method = "profile",
  ci_parm = "sigma",
  profile_precision = "fast"
)
#> <summary.drmTMB>
#> estimator: ML
#> confidence intervals: profile, level = 0.95
#>                    estimate  std_error   conf.low  conf.high conf.level
#> mu:(Intercept)     0.590000 0.03674235  0.5179863  0.6620137       0.95
#> mu:x               0.420000 0.03000000  0.3612011  0.4787989       0.95
#> sigma:(Intercept) -2.701839 0.35355327 -3.3947906 -2.0088873       0.95
#>                   conf.method conf.status profile.boundary profile.message
#> mu:(Intercept)           wald        wald               NA            <NA>
#> mu:x                     wald        wald               NA            <NA>
#> sigma:(Intercept)        wald        wald               NA            <NA>
#> Distributional, random-effect, scale, and correlation parameters:
#>                  component  dpar       term   estimate  std_error    scale
#> sigma distributional-scale sigma (constant) 0.06708204 0.02371707 response
#>         conf.low conf.high
#> sigma 0.03817676 0.1644424
#> logLik: 5.132
#> convergence: 0
if (requireNamespace("emmeans", quietly = TRUE)) {
  emmeans::emmeans(fit, specs = "x", at = list(x = c(-1, 0, 1)))
}
#>   x emmean     SE  df asymp.LCL asymp.UCL
#>  -1   0.17 0.0561 Inf     0.060     0.280
#>   0   0.59 0.0367 Inf     0.518     0.662
#>   1   1.01 0.0367 Inf     0.938     1.082
#> 
#> Confidence level used: 0.95

Usage

Arguments

Value

See also

Examples