The `rtmb_model` function acts as the core constructor for compiling and combining user-defined data with the model code (defined via `rtmb_code`). It generates an `RTMB_Model` (R6 class) instance, which serves as the foundation for performing Bayesian inference, including Maximum A Posteriori (MAP) estimation, Variational Inference (ADVI), and Markov Chain Monte Carlo (MCMC) sampling.
Usage
rtmb_model(
data,
code,
par_names = list(),
init = NULL,
view = NULL,
fixed = NULL,
silent = FALSE
)Arguments
- data
A named list containing observation data and constants (e.g., sample size, matrices) used in the model.
- code
A model definition block generated by
rtmb_code(...)(must includeparametersandmodelblocks).- par_names
A named list of character vectors corresponding to the dimensions of specific parameters (optional).
- init
A list or numeric vector of initial values for parameters (optional). If not specified, initialized randomly.
- view
Character vector of parameter names to be displayed preferentially at the top when outputting results like
summary()(optional).- fixed
A named list of parameter values to fix (optional). Useful for scoring or plug-in estimation where some parameters (e.g., item parameters) are fixed to known values.
- silent
Logical; if TRUE, suppresses diagnostic messages during model creation. Default is FALSE.
Value
An RTMB_Model class instance with a compiled and pre-tested automatic differentiation function.
An RTMB_Model class instance with a compiled and pre-tested automatic differentiation function.
Details
Model Compilation and Pre-checking: When this function is called, it evaluates the provided data and model blocks. It performs a "sandbox execution" (pre-check) using dummy initial values to dynamically detect common structural errors—such as undefined variables, out-of-bounds indices, or incompatible matrix operations—before proceeding to the computationally expensive Automatic Differentiation (MakeADFun) phase. Cryptic backend errors are caught and translated into user-friendly hints.
Writing AD-Compatible Code (Important):
To ensure the model is differentiable, you must follow specific syntax rules
when writing code within rtmb_code. Avoid discrete branching (if, ifelse)
based on parameters and use numerically stable functions.
See rtmb_syntax for a detailed guide on Automatic Differentiation requirements.
Initial Values (init):
Initial parameter values can be specified as a flat numeric vector or a named list.
If a partial list is provided, the unspecified parameters are automatically initialized
with random values drawn from a uniform distribution on the unconstrained scale.
If init = NULL, all parameters are initialized randomly.
Parameter Labeling (par_names):
By default, vector or matrix parameters are displayed with numeric indices (e.g., mu[1]).
You can pass a named list of character vectors to par_names to assign meaningful
labels to specific dimensions (e.g., mu[Control]), vastly improving the readability
of summary outputs and trace plots.
Available Inference Methods on the Returned Object:
The returned RTMB_Model instance provides the following core methods:
$optimize(...): Performs Maximum A Posteriori (MAP) or Maximum Likelihood estimation. Returns aMAP_Fitobject.$sample(...): Draws posterior samples using the NUTS (No-U-Turn Sampler) algorithm. Returns anMCMC_Fitobject.$variational(...): Performs Mean-field or Full-rank Automatic Differentiation Variational Inference (ADVI). Returns aVB_Fitobject.
Examples
# \donttest{
# Simulate data for 3 groups
set.seed(123)
N <- 60
group_idx <- sample(1:3, N, replace = TRUE)
group_names <- c("Control", "Treatment_A", "Treatment_B")
# True group means: Control = 0, Treatment_A = 2, Treatment_B = -1
true_means <- c(0, 2, -1)
y <- true_means[group_idx] + rnorm(N, mean = 0, sd = 0.5)
data_list <- list(N = N, K = 3, group_idx = group_idx, y = y)
# Define the model using rtmb_code
model_code <- rtmb_code(
parameters = {
mu = Dim(K) # Vector of length K (group means)
sigma = Dim(1, lower = 0) # Scalar (residual standard deviation)
},
model = {
# Priors
for (k in 1:K) mu[k] ~ normal(0, 10)
sigma ~ exponential(1)
# Likelihood
for (i in 1:N) {
y[i] ~ normal(mu[group_idx[i]], sigma)
}
}
)
# --- 1. Basic Model Creation ---
# Create the RTMB_Model object
mod_basic <- rtmb_model(
data = data_list,
code = model_code
)
#> Pre-checking model code...
#> Checking RTMB setup...
# Perform Maximum A Posteriori (MAP) estimation
map_basic <- mod_basic$optimize()
#> Starting RTMB optimization...
#>
# The summary displays default parameter names: mu[1], mu[2], mu[3]
map_basic$summary()
#>
#> Call:
#> MAP Estimation via RTMB
#>
#> Negative Log-Posterior: 46.99
#> Approx. Log Marginal Likelihood (Laplace): -53.43
#>
#> Point Estimates and 95% Wald CI:
#> variable Estimate Std. Error Lower 95% Upper 95%
#> mu[1] -0.12319 0.09499 -0.30936 0.06298
#> mu[2] 2.15920 0.10806 1.94742 2.37099
#> mu[3] -1.11887 0.09722 -1.30942 -0.92832
#> sigma 0.44555 0.04045 0.37292 0.53232
#>
# --- 2. Optional: Adding Custom Parameter Names and initial values ---
# You can optionally use 'par_names' to assign meaningful labels
# to vector or matrix elements for easier interpretation.
mod_named <- rtmb_model(
data = data_list,
code = model_code,
init = list(mu = rep(0, 3), sigma = 1),
par_names = list(mu = group_names)
)
#> Pre-checking model code...
#> Checking RTMB setup...
map_named <- mod_named$optimize()
#> Starting RTMB optimization...
#>
# The summary now displays: mu[Control], mu[Treatment_A], mu[Treatment_B]
map_named$summary()
#>
#> Call:
#> MAP Estimation via RTMB
#>
#> Negative Log-Posterior: 46.99
#> Approx. Log Marginal Likelihood (Laplace): -53.43
#>
#> Point Estimates and 95% Wald CI:
#> variable Estimate Std. Error Lower 95% Upper 95%
#> mu[Control] -0.12319 0.09499 -0.30936 0.06298
#> mu[Treatment_A] 2.15920 0.10806 1.94742 2.37099
#> mu[Treatment_B] -1.11887 0.09722 -1.30942 -0.92832
#> sigma 0.44555 0.04045 0.37292 0.53232
#>
# }