Prior Constructors

bgms 0.2.0 replaces the loose scalar prior arguments of earlier versions with a small set of prior-object constructors. Each constructor returns an S3 object that is passed to bgm() or bgmCompare(). Three classes of priors are exported:

Class	Used for	Constructors
`bgms_parameter_prior`	Real-valued model parameters (interactions, thresholds, continuous means)	`cauchy_prior()`, `normal_prior()`, `beta_prime_prior()`
`bgms_scale_prior`	Positive scale parameters (precision-matrix diagonal)	`gamma_prior()`, `exponential_prior()`
`bgms_indicator_prior`	Inclusion indicators (edge selection, difference selection)	`bernoulli_prior()`, `beta_bernoulli_prior()`, `sbm_prior()`

The legacy scalar arguments (pairwise_scale, main_alpha, main_beta, inclusion_probability, beta_bernoulli_alpha/beta, beta_bernoulli_alpha_between/beta_between, dirichlet_alpha, lambda, difference_probability) still work but emit a lifecycle warning and forward to the equivalent prior object.

Parameter priors

Priors on real-valued parameters. Used for interaction_prior, threshold_prior, and means_prior arguments of bgm() / bgmCompare().

`cauchy_prior()`

Cauchy(0, scale) prior. Produces heavy-tailed shrinkage toward zero. It is the opt-in alternative for pairwise interactions in both bgm() and bgmCompare(), whose shared default is normal_prior(scale = 1).

cauchy_prior(scale = 1)

Argument	Description
`scale`	Positive numeric. Scale (half-width at half-maximum) of the Cauchy distribution. Default: `1`.

Returns a bgms_parameter_prior object with family = "cauchy".

`normal_prior()`

Normal(0, scale) prior. Lighter-tailed than Cauchy, and the default for pairwise interactions in both bgm() and bgmCompare(), which also takes it as the default slab family for group differences. The lighter tails also make it the better choice for simulation studies, where a Cauchy prior can generate data with extreme parameter values.

normal_prior(scale = 1)

Argument	Description
`scale`	Positive numeric. Standard deviation of the Normal distribution. Default: `1`.

Returns a bgms_parameter_prior object with family = "normal".

`beta_prime_prior()`

Beta-prime prior, the default for threshold parameters. A threshold \(\mu\) has this prior when its logistic transform follows a Beta distribution: \(\mu = \text{logit}(Y)\) with \(Y \sim \text{Beta}(\alpha, \beta)\). The name comes from the equivalent formulation \(e^{\mu} = Y/(1-Y) \sim \text{Beta-prime}(\alpha, \beta)\). The shape parameters control where prior mass sits: \(\alpha\) governs the upper tail (large thresholds) and \(\beta\) the lower tail; the default \(\alpha = \beta = 0.5\) gives a heavy-tailed prior symmetric around \(\mu = 0\).

beta_prime_prior(alpha = 0.5, beta = 0.5)

Argument	Description
`alpha`	Positive numeric. First shape parameter. Default: `0.5`.
`beta`	Positive numeric. Second shape parameter. Default: `0.5`.

Returns a bgms_parameter_prior object with family = "beta-prime".

Scale priors

Priors on positive scale parameters, currently used only for the diagonal of the precision matrix in GGM and mixed MRF models (precision_scale_prior argument of bgm()).

Both constructors accept the rate in one of two frames — supply one of the two arguments, not both:

rate (raw frame): the prior applies to the precision diagonal as-is.
eta (standardized frame): the rate on the diagonal in the coordinate system where the pairwise (slab) prior has unit scale. eta fixes the scale of the diagonal relative to the slab, and the raw rate is derived at fit time as eta / s, where s is the scale of the interaction_prior. At fixed eta, graph and partial-correlation inference is invariant to the slab scale, so the standardized frame keeps the prior geometry fixed when the slab scale changes. It requires an interaction prior with a scale parameter (normal_prior() or cauchy_prior()).

With neither argument supplied, the default is the standardized frame with eta = 1. Small eta places the prior mass well inside the positive-definite cone; large eta places mass near the cone boundary.

`gamma_prior()`

Gamma(shape, rate) prior. gamma_prior(shape = 1) is equivalent to exponential_prior() with the same rate argument.

gamma_prior(shape = 1, rate = NULL, eta = NULL)

Argument	Description
`shape`	Positive numeric. Shape parameter of the Gamma distribution. Default: `1`.
`rate`	Positive numeric. Rate parameter in the raw frame. Mutually exclusive with `eta`.
`eta`	Positive numeric. Rate parameter in the standardized frame (unit slab scale). Mutually exclusive with `rate`. Default when neither is supplied: `1`.

Returns a bgms_scale_prior object with family = "gamma".

`exponential_prior()`

Exponential prior. Convenience constructor equivalent to gamma_prior(shape = 1) with the same rate argument. The default precision_scale_prior in bgm() is exponential_prior(eta = 1).

exponential_prior(rate = NULL, eta = NULL)

Argument	Description
`rate`	Positive numeric. Rate parameter in the raw frame. Mutually exclusive with `eta`.
`eta`	Positive numeric. Rate parameter in the standardized frame (unit slab scale). Mutually exclusive with `rate`. Default when neither is supplied: `1`.

Returns a bgms_scale_prior object with family = "exponential".

Indicator priors

Priors on inclusion indicators. Used for the edge_prior argument of bgm() and the difference_prior argument of bgmCompare().

`bernoulli_prior()`

Fixed inclusion probability for each indicator. The simplest indicator prior; the inclusion probability does not change during sampling.

bernoulli_prior(inclusion_probability = 0.5)

Argument	Description
`inclusion_probability`	Numeric scalar in \((0, 1)\), or a symmetric \(p \times p\) matrix for edge-specific probabilities. Default: `0.5`.

Returns a bgms_indicator_prior object with family = "Bernoulli".

`beta_bernoulli_prior()`

Beta-Bernoulli prior on inclusion. The shared inclusion probability is drawn from a Beta(\(\alpha\), \(\beta\)) prior and learned from the data.

beta_bernoulli_prior(alpha = 1, beta = 1)

Argument	Description
`alpha`	Positive numeric. First shape parameter of the Beta distribution. Default: `1`.
`beta`	Positive numeric. Second shape parameter of the Beta distribution. Default: `1`.

Returns a bgms_indicator_prior object with family = "Beta-Bernoulli".

`sbm_prior()`

Stochastic Block Model prior. Variables are assigned to latent clusters, with separate Beta priors on within-cluster and between-cluster inclusion probabilities. See Edge Clustering and SBM Prior for the full formulation.

sbm_prior(
  alpha           = 1,
  beta            = 1,
  alpha_between   = 1,
  beta_between    = 1,
  dirichlet_alpha = 1,
  lambda          = 1
)

Argument	Description
`alpha`, `beta`	Positive numeric. Shape parameters of the Beta prior for within-cluster edge inclusion. Defaults: `1`.
`alpha_between`, `beta_between`	Positive numeric. Shape parameters of the Beta prior for between-cluster edge inclusion. Defaults: `1`.
`dirichlet_alpha`	Positive numeric. Concentration parameter of the Dirichlet prior on cluster assignments. Default: `1`.
`lambda`	Positive numeric. Rate parameter of the shifted-Poisson prior on the number of clusters \(B\), under which \(B - 1 \sim \text{Poisson}(\lambda)\), so that the prior expectation is \(1 + \lambda\) clusters. Default: `1`.

Returns a bgms_indicator_prior object with family = "Stochastic-Block".

Examples

# bgm with explicit prior choices
fit = bgm(
  x,
  interaction_prior = cauchy_prior(scale = 2.5),
  threshold_prior   = beta_prime_prior(0.5, 0.5),
  edge_prior        = beta_bernoulli_prior(1, 1)
)

# Mixed MRF with normal priors on continuous means and the precision diagonal
fit = bgm(
  x,
  variable_type         = c("ordinal", "ordinal", "continuous", "continuous"),
  means_prior           = normal_prior(scale = 0.5),
  precision_scale_prior = exponential_prior(rate = 1)  # raw frame
)

# GGM with a wider slab; eta keeps the prior geometry fixed relative to it
fit = bgm(
  x,
  variable_type         = "continuous",
  interaction_prior     = normal_prior(scale = 2.5),
  precision_scale_prior = exponential_prior(eta = 1)  # standardized frame
)

# SBM-structured edge selection
fit = bgm(
  x,
  edge_prior = sbm_prior(alpha = 8, beta = 1, alpha_between = 1, beta_between = 8)
)

# Group comparison with Beta-Bernoulli difference selection
fit = bgmCompare(
  x, y,
  difference_prior = beta_bernoulli_prior(1, 1)
)

Parameter priors

cauchy_prior()

normal_prior()

beta_prime_prior()

Scale priors

gamma_prior()

exponential_prior()