Skip to contents

Random-effect scale formula syntax

Source: R/random-effect-scale-formulas.R
random_effect_scale_formulas.Rd

sd(group) ~ predictors and its siblings are formula-only syntax for modelling random-effect standard deviations. They are captured by drm_formula() or bf() and are not evaluated as ordinary R calls. In particular, sd(group) ~ predictors does not replace stats::sd().

Value

A formula-syntax reference page; no object is returned.

Details

The currently documented syntax is:

  • sd(group) ~ predictors for univariate Gaussian location random-effect scale models;

  • sd1(group) ~ predictors and sd2(group) ~ predictors for bivariate Gaussian location random-effect scale models targeting mu1 and mu2;

  • sd(group, level = "phylogenetic") ~ predictors for univariate Gaussian phylogenetic location random-effect scale models;

  • sd1(group, level = "phylogenetic") ~ predictors and sd2(group, level = "phylogenetic") ~ predictors for bivariate Gaussian phylogenetic location random-effect scale models targeting mu1 and mu2.

sd(group, level = "phylogenetic") and its bivariate siblings are the generic spelling for these targets. The historical spellings sd_phylo(species) ~ predictors, sd_phylo1(species) ~ predictors, and sd_phylo2(species) ~ predictors are deprecated (soft): they still parse and fit identically, but emit a one-time deprecation warning per session and should not be used in new formulas. Future spatial, animal-model, and user-supplied relatedness direct-SD routes are planned to use the same level = grammar, such as sd(group, level = "spatial") or sd1(group, level = "animal"), rather than adding parallel sd_spatial*(), sd_animal*(), and sd_relmat*() families.

These formulas model the standard deviation of a latent random-effect block. They are distinct from residual scale formulas such as sigma ~ predictors and from latent correlation formulas such as corpair(). Non-Gaussian random-effect scale formulas, spatial/animal/relmat direct-SD formulas, and explicit coefficient-specific targets such as sd(group, dpar = "mu", coef = "slope") ~ predictors remain planned.

Examples

bf(y ~ x + (1 | id), sigma ~ z, sd(id) ~ habitat)
#> <drm_formula>
#> y ~ x + (1 | id)
#> sigma ~ z
#> sd(id) ~ habitat

bf(
  mu1 = y1 ~ x + (1 | p | id),
  mu2 = y2 ~ x + (1 | p | id),
  sd1(id) ~ habitat,
  sd2(id) ~ habitat,
  rho12 = ~ x
)
#> <drm_formula>
#> mu1 = y1 ~ x + (1 | p | id)
#> mu2 = y2 ~ x + (1 | p | id)
#> sd1(id) ~ habitat
#> sd2(id) ~ habitat
#> rho12 = ~x

bf(
  y ~ x + phylo(1 | species, tree = tree),
  sd(species, level = "phylogenetic") ~ ecology
)
#> <drm_formula>
#> y ~ x + phylo(1 | species, tree = tree)
#> sd(species, level = "phylogenetic") ~ ecology