Skip to contents

One shared trait variance: scalar(0 + trait | g)

Source: R/brms-sugar.R
scalar.Rd

Soft-deprecated; use indep(0 + trait | g, common = TRUE). No-prefix name for the one-shared-variance trait covariance: a single variance \(\sigma^2\) shared by every trait with zero cross-trait covariance, giving \(\boldsymbol\Sigma_T = \sigma^2 \mathbf I_T\). It is the most parsimonious mode in the covariance grid.

Usage

scalar(formula)

Arguments

formula

0 + trait | g style formula (LHS is the trait factor, typically 0 + trait; RHS is the grouping factor).

Value

A formula marker; never evaluated.

Details

scalar() desugars byte-identically to indep(0 + trait | g, common = TRUE) – the two spellings fit the same model, tying all trait variances to one shared parameter. Use scalar() when you want to commit explicitly to one shared trait-scale variance; use indep() for a separate variance per trait, or dep() / latent() for cross-trait covariance.

The shared variance still couples grouping levels through the source (identity for the no-prefix row). The source-specific phylo_scalar(), animal_scalar(), and spatial_scalar() carry the same one-shared-variance meaning on their respective relationship operators.

See also

indep(), dep(), latent(), phylo_scalar(), extract_Sigma().

Examples

sim <- simulate_unit_trait(
  n_units = 40, n_obs_per_unit = 3, n_traits = 3,
  psi_B = rep(0.4, 3), seed = 1
)
df <- sim$data

# \donttest{
# One shared trait variance across all traits (identity cross-trait).
# scalar() is compatibility syntax and warns once per session.
fit <- gllvmTMB(value ~ 0 + trait + scalar(0 + trait | unit),
                data = df, trait = "trait", unit = "unit")
#> Warning: ! Formula keyword `scalar()` is soft-deprecated as of gllvmTMB 0.5.0
#>   (compatibility syntax).
#> ℹ The covariance grid now has three modes: `indep()`, `dep()`, `latent()`. The
#>   one-shared-variance case is `common = TRUE`.
#> → Use `indep(..., common = TRUE)`; it fits the same model.

# Equivalent longhand:
fit2 <- gllvmTMB(value ~ 0 + trait + indep(0 + trait | unit, common = TRUE),
                 data = df, trait = "trait", unit = "unit")
c(scalar = logLik(fit), indep_common = logLik(fit2))
#>       scalar indep_common 
#>     -457.612     -457.612 
# }