Setting manual priors

Scott Claessens

2026-08-19

Introduction

This vignette describes how to set manual priors on parameters with the coevolve package. It describes the default priors that are used by the package and how users can specify their own priors.

Default priors

If the user does not explicitly declare any priors using the prior argument in coev_fit(), then the model will default to the following priors:

Parameter label	Parameter description	Default prior	Constraint
A_diag	Autoregressive selection effects	std_normal()	Negative
A_offdiag	Cross selection effects	std_normal()
L_R	Cholesky factor for drift matrix	lkj_corr_cholesky(4)
Q_sigma	Drift standard deviations	std_normal()	Positive
eta_anc	Root ancestral states	std_normal()
c	Ordinal cutpoints	normal(0, 2)
shape	Shape parameters (gamma distribution)	gamma(0.01, 0.01)	Positive
sigma_dist	Standard deviations for spatial GPs	exponential(1)	Positive
rho_dist	Rho parameters for spatial GPs	exponential(5)	Positive
sigma_residual	Residual standard deviations	exponential(1)	Positive
L_residual	Cholesky factor for residual correlations	lkj_corr_cholesky(4)

In addition, the default prior for phi (the overdispersion parameter for the negative-binomial distribution) is scaled automatically based on the variance of the data.

These default priors were chosen to be weakly regularising, which improves model fitting and conservatism in parameter estimates. However, we recommend that users assess the suitability of these default priors by fitting the model with coev_fit(..., prior_only = TRUE) and then plotting prior predictive checks for all variables using the coev_plot_predictive_check() function.

Setting manual priors

When the package writes the underlying Stan code for the model, it sets these default priors in the model block. For example, we can extract the section of the Stan code that sets the priors from an example model:

# generate the stan code with default priors
stan_code_default <-
  coev_make_stancode(
    data = authority$data,
    variables = list(
      religious_authority = "ordered_logistic",
      political_authority = "ordered_logistic"
    ),
    id = "language",
    tree = authority$phylogeny
  )

# extract the priors section from the model block
cat(substr(stan_code_default, 8739, 9088))

  // priors
  b ~ std_normal();
  for (t in 1:N_tree) {
    eta_anc[t] ~ std_normal();
    for (i in 1:(N_seg - 1)) z_drift[t, i] ~ std_normal();
    to_vector(terminal_drift[t]) ~ std_normal();
  }
  A_offdiag ~ std_normal();
  A_diag ~ std_normal();
  Q_sigma ~ std_normal();
  L_R ~ lkj_corr_cholesky(4);
  c1 ~ normal(0, 2);
  c2 ~ normal(0, 2);

If we wanted to set manual priors to replace some of these, we need only declare our manual priors as Stan-readable strings using the prior argument. This argument accepts a named list of priors for the model:

# generate the stan code with manual priors
stan_code_manual <-
  coev_make_stancode(
    data = authority$data,
    variables = list(
      religious_authority = "ordered_logistic",
      political_authority = "ordered_logistic"
    ),
    id = "language",
    tree = authority$phylogeny,
    prior = list(
      A_diag = "normal(0, 2.5)",
      A_offdiag = "normal(0, 2.5)",
      Q_sigma = "exponential(3)",
      c = "normal(0, 3)"
    )
  )

# extract the priors section from the model block
cat(substr(stan_code_manual, 8739, 9093))

  // priors
  b ~ std_normal();
  for (t in 1:N_tree) {
    eta_anc[t] ~ std_normal();
    for (i in 1:(N_seg - 1)) z_drift[t, i] ~ std_normal();
    to_vector(terminal_drift[t]) ~ std_normal();
  }
  A_offdiag ~ normal(0, 2.5);
  A_diag ~ normal(0, 2.5);
  Q_sigma ~ exponential(3);
  L_R ~ lkj_corr_cholesky(4);
  c1 ~ normal(0, 3);
  c2 ~ normal(0, 3);

We could fit the model with these manual priors by setting the same prior argument when running the coev_fit() function.

Limitations on setting priors

Because of the way the Stan code is written, priors are currently set globally. For example, it is not possible to set one prior for one cross-selection effect and a different prior for another cross-selection effect. Users must set a global prior for all cross-selection effects by setting prior = list(A_offdiag = ...). To set different priors for different parameters, we recommend that users generate the Stan code and modify it manually to suit their needs.