Writing Model Codes

1-1. parameters block

This block is for declaring the parameters you want to estimate in the model. You use the Dim() function to specify the dimension and constraints (e.g., lower and upper bounds) of the variables.

Example Code:

parameters = {
  # Scalar parameter (with lower bound of 0)
  sigma = Dim(lower = 0)
  
  # Vector parameter (length N)
  mu = Dim(N)
  
  # Matrix parameter (N rows, M columns)
  X = Dim(N, M)
}

Here we are defining generic continuous parameters, but by using the type argument you can define parameters (types) with more complex structures, such as “correlation matrices” or “sum-to-zero vectors” (see “3. About Parameter Types (Dim)” below for details).

1-2. model block

This is the heart of the model where you define priors and the likelihood (the data generating process). Similar to Stan, using the ~ (tilde) sampling syntax is recommended.

model = {
  # Priors
  mu ~ normal(0, 10)
  sigma ~ exponential(1)

  # Likelihood
  Y ~ normal(mu, sigma)
}

The same model can also be written by explicitly adding log densities:

model = {
  lp <- lp + normal_lpdf(mu, 0, 10)
  lp <- lp + exponential_lpdf(sigma, 1)
  lp <- lp + normal_lpdf(Y, mu, sigma)
}

In other words, Y ~ normal(mu, sigma) and lp <- lp + normal_lpdf(Y, mu, sigma) are two ways to write the same model. The ~ syntax is usually easier to read, while lp <- lp + ..._lpdf(...) is useful when you need to build a custom likelihood. lp is reserved for accumulating log probability, so do not declare it in the parameters block or use it as an ordinary working variable.

1-3. setup block

This block is executed exactly once before the model computations begin. It is primarily used to extract data sizes (number of rows/columns) as variables from the data list passed from R, and to create constants required for computations.

Example Code:

setup = {
  N <- length(Y)  # Get the sample size of the observed data
  P <- ncol(X)    # Get the number of columns in the design matrix (number of predictors)
}

1-4. transform block

This block is for creating derived variables (such as the mean mu or linear predictors) necessary for likelihood calculations from parameters and data. The variables created here can be used directly within the model block.

[!IMPORTANT] The derived variables calculated here are automatically saved inside the model object. Not only can you obtain samples of their posterior distributions after estimation, but when you run MAP estimation (optimize), standard errors and 95% confidence intervals for these derived variables are also automatically calculated and output using the delta method.

1-5. generate block

This block is used for creating predictive distributions for Posterior Predictive Checks (PPC) and for generating new quantities of interest calculated from estimated parameters.

[!IMPORTANT] Computations written in the generate block are not included in the likelihood evaluation (Automatic Differentiation calculations) and can be executed post-hoc after the estimation is fully complete. Therefore, no matter how computationally heavy the operations written here are, they will not negatively affect the estimation speed (MAP or MCMC). Also, if you forgot to write something during model definition or later decide you want to compute another quantity, you can calculate these retroactively by calling the mdl$generated_quantities(new_generate_code) method on the estimated model object.

2-1. Common Probability Density and Mass Functions

Continuous Probability Distributions (LPDF)

Discrete Probability Distributions (LPMF)

2-2. Advanced Probability Distributions

Distributions are also provided to improve computational stability or for specific modeling purposes.

2-3. Probability Distributions for Special Types

Distributions tailored for matrices, multivariate data, and specific model structures.