Can I fit and report this model?

Use this page before putting a drmTMB result in a manuscript. A model that converges may still be outside the part of the package for which a point estimate, an interval, or both can be reported. This guide separates those questions and gives a practical alternative when a model is outside scope.

Terms used on this page

mu is the location parameter: the family-specific centre of the response. sigma is scale: residual variability. nu is shape: a feature beyond location and scale in families such as Student-t. Coscale includes residual correlation rho12, the association left between two responses after their locations and scales are modelled. sd(group) is among-group random-effect variation, not residual sigma. phylo() and spatial() specify phylogenetic and coordinate-structured random effects. meta_V(V = V) supplies known sampling covariance; meta_known_V(V = V) is its deprecated compatibility alias. This page does not use tau, because it is not a general drmTMB parameter name.

Reader decision path

Use this three-step path when choosing and reporting a model:

1. What can the package fit? Start with What can I fit today? to choose a documented family, parameter, and dependence structure.
2. What are the important limits? Use the exact reporting checks below before treating a fitted value or interval as a scientific result.
3. Which tutorial comes next? Follow the linked family, structured-effect, bivariate, or missing-data tutorial after you have identified the route that matches your question.

Before reporting

Important limits

Start with these four questions:

1. Can I fit this exact model? The family, parameter, random-effect shape, and missing-data option all matter.
2. Can I report its point estimate? A working extractor alone is not enough.
3. Can I report this interval? An available interval is not necessarily calibrated for every dataset.
4. What should I do if the answer is no? The sections below name a simpler supported model or a more cautious interpretation.

Before copying a result, run check_drm(fit). Check convergence, the fixed- effect gradient, and Hessian diagnostics; then inspect conf.status, profile.boundary, and any failed bootstrap refits for the interval you plan to report. A printed interval is not permission to ignore a boundary or failed refit warning.

Evidence and exact tested scopes

The labels on this page are deliberately plain.

• Point estimate and interval: the stated combination has been checked in the model settings described here. Keep the stated limitation in your report.
• Point estimate only: fitting and recovery of the estimate have been checked, but an interval has not yet been calibrated for that use.
• Feasibility only: the model can be fitted and its result extracted, but it is not a scientific reporting route.
• Not available: drmTMB rejects the request or it lies outside the package’s current supported surface. Use the named alternative instead.

These are boundaries, not a hierarchy of scientific importance. A focused, well-supported model is preferable to a more elaborate model whose uncertainty has not been established.

Common reportable models

Fixed effects and ordinary random effects

For ordinary fixed-effect models, binomial, Poisson, negative-binomial, strict continuous-proportion (beta_family()), and Gaussian examples have checked Wald intervals in the tested settings. The strict beta family requires responses strictly inside (0, 1); use zero_one_beta() when exact zeroes or ones are meaningful outcomes. These results do not create a universal minimum sample-size rule, so retain ordinary convergence and diagnostic checks.

Negative-binomial location–scale models (mu and sigma ~ x) and strict beta location–scale models have the same point-and-interval permission for their tested fixed-effect forms. For the latter, the interior-proportion requirement still applies.

Independent mean-side random slopes are more limited. For binomial, skew-normal, Tweedie, and zero-one-beta models, the selected independent-slope forms have assessed profile intervals under maximum likelihood. Treat that as a narrow permission: use the profile interval only after the model has passed its own diagnostics, do not substitute a Wald interval or make a point-bias claim, and do not generalise it to correlated, labelled, or more complex slopes.

Gaussian structured random effects: selected anchor cells

The most developed structured models are Gaussian ones. Checked intervals cover a structured Gaussian mean intercept, selected Gaussian scale effects with one numeric slope, and selected bivariate Gaussian mean slopes. Their interval method is part of the result: for the checked Gaussian mean-intercept forms, use the default bias-corrected, small-sample-t Wald interval. For the selected bivariate mean-slope forms, use plain confint(fit) and do not turn off its default small-sample correction. For the checked Gaussian scale-slope forms, the assessed interval is the uncorrected log-standard-deviation Wald interval; profile intervals remain feasibility checks at eight structured levels rather than reporting intervals. Other structured Gaussian shapes do not inherit these interval permissions.

For a pure Gaussian mean model, REML is available for an unlabelled spatial, animal, or relatedness intercept, or for that intercept plus one independent numeric slope, when sigma ~ 1. The following are the three permitted shapes (replace the object names with objects from your analysis):

fit_spatial_reml <- drmTMB(
  bf(y ~ x + spatial(1 + x | site, coords = coords), sigma ~ 1),
  family = gaussian(), data = dat, REML = TRUE
)
fit_animal_reml <- drmTMB(
  bf(y ~ x + animal(1 + x | id, A = A), sigma ~ 1),
  family = gaussian(), data = dat, REML = TRUE
)
fit_relmat_reml <- drmTMB(
  bf(y ~ x + relmat(1 + x | id, K = K), sigma ~ 1),
  family = gaussian(), data = dat, REML = TRUE
)

For those exact forms, a direct profile interval for the structured standard deviation is appropriate only within the configurations already checked. Do not generalise it to several slopes, labelled covariance blocks, changing residual scale, incomplete pairs, weights, meta_V(), direct-SD models, or corpair(). Pedigree and Ainv animal inputs and relmat Q are accepted representations, but they do not automatically inherit every uncertainty result obtained with A and K.

The structured scale is the multiplier of the supplied covariance matrix. If the fitted scale is s_j and the supplied matrix is K_h, the covariance is s_j^2 K_h; the marginal standard deviation at level i is s_j sqrt(K_h[ii]). Thus the fitted scale equals a level-specific standard deviation only when that matrix diagonal is one.

Structured models with point estimates only

Structured Poisson and negative-binomial mean models have a useful but narrower permission: report the point estimate for the supported single-effect forms, but not an interval as if it were calibrated. A small number of named structured beta, Student-t, Gamma, and zero-one-beta forms likewise have point-estimate support only; use their family article before treating a fit as reportable.

Matching bivariate Gaussian spatial or supplied-relatedness intercepts in both mean formulas also have point-estimate support when the two responses are complete, use the same named structure, and retain simple constant scale and association formulas. Do not extend this to slopes, extra random effects, weights, missing responses, or a different structure in each mean.

Lognormal, skew-normal, and Tweedie models do not generally accept structured random effects. For count data, use an ordinary Poisson or negative-binomial structured mean model where it answers the scientific question; otherwise use fixed effects or a Gaussian model on an appropriate transformed response.

REML boundaries

REML is a Gaussian method in drmTMB, not a general option for every family or formula. Outside the Gaussian forms described above, use maximum likelihood (REML = FALSE). A binomial model with one ordinary, unlabelled mean-side intercept or independent slope can be fitted with REML = TRUE, but treat it as a feasibility comparison, not as a scientific estimate. Fixed-only, correlated, labelled, structured, missing-response, and other non-Gaussian REML requests are not available.

Higher-order covariance blocks and broad derived-correlation intervals are not general reporting routes. Use the fitted point estimate only if it is useful descriptively, or try profile_targets(fit) for a direct target that the fitted model already exposes.

Association and bivariate models

For complete pairs with fixed-effect association, vcov() and confint() can provide association-link (alpha) uncertainty when the fit-specific covariance diagnostics pass. Transforming an intercept-only association with confint(object, type = "eta"), or obtaining pointwise association predictions, does not add a simultaneous-band or universal-coverage claim.

The strongest current association result is an intercept-only association between a literal Bernoulli response and an ordinary negative-binomial response, in the high-information setting that has been checked. Lower-information fits warn or withhold an interval when their diagnostics fail. Random effects, missing data, weights, offsets, REML, profiles, and simultaneous association bands are outside that interval result.

For a covariate-dependent residual correlation (rho12 ~ x), request intervals at the covariate values that answer your question with confint(fit, parm = "rho12", newdata = grid, method = "profile") or predict_parameters(fit, newdata = grid, dpar = "rho12", conf.int = TRUE). Treat these as fit-specific intervals, not as a calibrated guarantee.

Missing data

Missing responses and missing predictors are modelled in the likelihood; this is not multiple imputation. Response masking is available for Gaussian, bivariate Gaussian, Student-t, skew-normal, lognormal, Gamma, Tweedie, binomial, Poisson, negative-binomial, strict beta, zero-one beta, beta-binomial, cumulative-logit, and non-hurdle truncated-negative-binomial models. Check the worked guide in vignette("missing-data") before using it in a new family.

Missing-predictor support is narrower:

Response model	Missing-predictor support
Gaussian location model	Broad catalogue of predictor models
Negative-binomial (nbinom2()) model	One binary or one Gaussian missing predictor
Binomial, Poisson, strict beta, lognormal, Gamma, Student-t, or beta-binomial model	One binary missing predictor
Other response models	Not available

Outside Gaussian response models, missing predictors are limited to the binary-predictor routes and the nbinom2() Gaussian-predictor route listed above. Do not combine multiple missing predictors, response masking and mi() in one fit, or random/structured/zero-inflated response terms with mi(). Multivariate missing-predictor models and missing-data EM, profile, and REML methods are not available.

Important limits and next tutorial

• A cumulative-logit random-slope method used in development is not exposed as a public reporting route. Use the ordinary public model only at the scope described above.
• The optional Julia engine does not yet provide general mixed-family inference. Use drmTMB’s default native engine when you need routine fitted values, covariance estimates, or fixed-effect intervals.
• When a structured scale interval is central to your conclusion, prefer a better-supported ordinary random intercept or a fixed-effect scale model if either answers the same question.
• If no route on this page covers your model, simplify the random-effect structure, use fixed effects, or choose a family whose boundary behaviour matches the response. Do not present an exploratory fit as a calibrated one.

Choose the next worked tutorial from response families, structured effects, bivariate models, or missing data. This page is deliberately a reporting guide: it tells you what to fit, what to report, and where to stop.