1. Overall Flow

At a high level, BayesRTMB proceeds as follows.

rtmb_code()
  -> rtmb_model()
    -> RTMB_Model
      -> build_ad_obj()
        -> RTMB::MakeADFun()
          -> sample() / optimize() / variational() / classic()
            -> MCMC_Fit / MAP_Fit / VB_Fit / Classic_Fit

Users usually write only rtmb_code() and call rtmb_model().

rtmb_model() checks the model code and data, then creates an RTMB_Model R6 object. This object stores the model definition, data, parameter declarations, transformation blocks, generated-quantity blocks, and wrapper metadata.

When an inference method is called, BayesRTMB builds the automatic differentiation object needed by RTMB::MakeADFun(). The resulting fit is returned as a method-specific object.

BayesRTMB is organized around the functional priority MCMC, MAP, VB, and then classical estimation. MCMC is the central method when the full posterior distribution matters. MAP provides fast point estimation and approximate checks. VB provides approximate inference for larger models. Classical estimation is a supplementary route for flat-prior wrapper models.

2. Blocks in rtmb_code()

rtmb_code() describes a model as a set of named blocks.

code <- rtmb_code(
  data = {
    # Declare data names used by the model
  },
  setup = {
    # Preprocess data
  },
  parameters = {
    # Declare estimable parameters
  },
  transform = {
    # Build linear predictors and derived quantities
  },
  model = {
    # Write likelihood and prior distributions
  },
  generate = {
    # Compute generated quantities after fitting
  }
)

Not every block is required. The minimal model usually needs only parameters and model.

parameters = {
  alpha <- Dim()
  beta  <- Dim(P)
  sigma <- Dim(lower = 0)
  r     <- Dim(G, random = TRUE)
}

transform = {
  mu <- alpha + X %*% beta
}

model = {
  beta ~ normal(0, 10)
  sigma ~ exponential(1)
  Y ~ normal(mu, sigma)
}

Y ~ normal(mu, sigma)

lp <- lp + normal_lpdf(Y, mu, sigma)

generate = {
  y_rep <- rnorm(length(Y), mu, sigma)
}

3. Parameter Representation

Users usually think about parameters on their natural constrained scale:

• sigma is positive;
• theta is between 0 and 1;
• ordered cutpoints must be increasing;
• simplex vectors must sum to 1.

Optimization and HMC are easier on unconstrained real-valued spaces. BayesRTMB therefore maintains two representations.

For example, sigma <- Dim(lower = 0) is displayed as a positive sigma, but internally it is transformed from an unconstrained value.

Important helper functions include:

• to_unconstrained();
• to_constrained();
• constrained_vector_to_list();
• unconstrained_vector_to_list();
• generate_flat_names().

These transformations are central to fixed, map, random effects, Laplace approximation, and printed summaries.

4. Jacobian Correction

When constrained parameters are transformed to an unconstrained space, density calculations can require a Jacobian adjustment.

If y is the natural constrained parameter and x is the unconstrained parameter, the relation is:

\[ \log p_X(x) = \log p_Y(y) + \log \left| \frac{dy}{dx} \right| \]

BayesRTMB users write models on the natural scale. Internally, functions such as to_unconstrained(), to_constrained(), and calc_log_jacobian() add the required correction depending on the inference route.

The target is controlled by jacobian_target.

For MCMC, BayesRTMB samples in the unconstrained space, so the posterior density generally uses jacobian_target = "all".

For optimize() with Laplace approximation, the density transformation needed for the integrated random side uses jacobian_target = "random".

For ordinary optimization without Laplace approximation, internal objective construction usually uses jacobian_target = "none".

Most users do not need to set this option directly. The distinction matters when understanding profile likelihoods, Laplace approximation, or low-level internals.

5. RTMB Automatic Differentiation Objects

RTMB provides an R interface to the TMB automatic differentiation engine.

BayesRTMB calls RTMB::MakeADFun() through RTMB_Model$build_ad_obj(). This creates an object that can evaluate function values, gradients, and Hessian-related quantities.

The model code is not compiled from a separate Stan-like language. Instead, the R model function is evaluated with AD objects. Arithmetic, matrix operations, distribution functions, and transformations are recorded as an automatic differentiation graph.

rtmb_model() performs pre-checks before fitting:

• undefined variables in setup or parameters;
• whether model and transform can run with initial values;
• whether log_prob returns a scalar;
• whether MakeADFun() can compute gradients.

These checks aim to catch structural problems before they become harder-to-read RTMB/TMB errors.

6. Inference Methods

fit <- mdl$sample()

fit <- mdl$optimize()

fit <- mdl$variational()

fit <- mdl$classic()

7. optimize() vs classic()

optimize() and classic() share low-level RTMB machinery, but their responsibilities differ.

optimize() is the API for MAP / ML / marginal MAP. It can be used with informative priors.

classic() is the API for frequentist interpretation of supported wrapper models with flat priors.

Internally, .fit_rtmb() builds the MakeADFun() object, runs optimization, and returns raw components such as sdreport() output. It does not itself construct user-facing fit objects.

This separation lets the same optimization engine support different summaries, degrees of freedom, prior correction, and post-processing behavior.

8. Laplace Approximation and random

In hierarchical, latent-variable, and mixed models, it is often better to integrate over some parameters rather than optimize all parameters as fixed effects.

Parameters declared with random = TRUE are eligible for Laplace approximation.

parameters = {
  alpha <- Dim()
  tau   <- Dim(lower = 0)
  r     <- Dim(G, random = TRUE)
}

With optimize(laplace = TRUE), BayesRTMB passes random-effect parameters to RTMB::MakeADFun(random = ...). In optimize(), laplace = TRUE is the default.

optimize(marginal = ...) can temporarily treat primary parameters as random so that marginal MAP / empirical Bayes style estimation can be performed. In flat-prior models, marginalizing fixed effects can correspond to restricted maximum likelihood (REML)-like estimation.

fit <- mdl$optimize(marginal = c("mean", "delta"))

Two internal sets are important:

In mixed models, both original random effects and primary parameters selected by marginal may be integrated by Laplace approximation. Therefore, laplace_random_vars can be broader than marginal_vars.

9. Standard Errors and Intervals

optimize() and classic() can report standard errors and intervals, not only point estimates.

Important se_method options include:

se_method = "none" is a lightweight mode. It does not mean that standard errors are zero; it means they are not calculated.

Derived quantities created in transform can be handled by the delta method or by simulation-based propagation. Generated quantities are naturally handled from MCMC draws or by post-estimation generation.

If sdreport() cannot provide reliable standard errors, BayesRTMB emits diagnostic messages. Examples include non-positive-definite Hessians, unavailable covariance matrices, Hessian fallbacks, and generalized-inverse fallbacks.

10. Writing AD-Friendly Code

RTMB model code looks like ordinary R code, but internally it is evaluated with automatic differentiation objects. Some ordinary R patterns can therefore be problematic.

# Avoid this pattern
if (sigma > 1) {
  lp <- lp + normal_lpdf(y, 0, sigma)
} else {
  lp <- lp + normal_lpdf(y, 0, 1)
}

11. Relationship to Stan, TMB, and RTMB

BayesRTMB uses RTMB as its computational backend. RTMB is an R interface to TMB’s automatic differentiation engine.

BayesRTMB is similar to Stan in that users write probabilistic models with constrained parameters and priors. It differs in that model code is written as R expressions through rtmb_code(), rather than in a separate Stan language file.

12. Summary

BayesRTMB’s internal structure can be summarized as follows.

• rtmb_code() describes a model as a block-structured object.
• rtmb_model() checks the data and code, then creates an RTMB_Model.
• RTMB_Model stores model code, data, parameter declarations, transformations, generated quantities, and wrapper metadata.
• build_ad_obj() creates the automatic differentiation object used by RTMB::MakeADFun().
• sample(), optimize(), variational(), and classic() run different inference methods from the same model representation.
• optimize() and classic() share a low-level engine, but their responsibilities and return objects are distinct.
• For Laplace approximation, the distinction between random = TRUE, marginal_vars, and laplace_random_vars is important.

For practical model-writing examples, see Writing Model Codes. To understand wrapper-generated models, see Wrapper Functions and print_code(). For a detailed mixed-model and GLMM workflow, see Hierarchical Models and GLMMs.