Skip to contents

Build a confirmatory lambda_constraint matrix from group membership

Source: R/confirmatory-lambda.R
confirmatory_lambda.Rd

Construct the n_species by d confirmatory loading-constraint matrix M from a discrete functional-group hypothesis. Each named group is pinned to load on a specific latent axis (zero on all other axes). By default no +1 anchors are applied. The latent axes already have unit variance and the lower-triangular form fixes the rotation, so a +1 anchor does not set a scale: it removes a free parameter and can bias the other loadings and unique variances (#1585). Anchors are an explicit opt-in via anchors. Groups present in group but absent from loads_on remain free on all axes.

Usage

confirmatory_lambda(
  species,
  group,
  d,
  loads_on,
  anchors = NA,
  axis_labels = NULL
)

Arguments

species

Character vector of species names. Becomes the rownames of the returned matrix. Must match the species (i.e. trait levels) used in the gllvmTMB() fit.

group

Character or factor vector parallel to species; the functional-group code for each species.

d

Integer; number of latent axes (matches the d argument of latent(0 + trait | site, d = d)).

loads_on

Named list or named integer vector mapping group code to latent axis index. For example, list(A = 1L, B = 2L) means species in group A load on axis 1 only (zero on all other axes), species in group B load on axis 2 only. Groups present in group but absent from loads_on remain free on all axes.

anchors

Opt-in +1 anchors. The default, NA, applies no anchor on any axis (a zeros-only pattern). A +1 anchor is a restriction, not a scale choice: the latent axes have unit variance, so pinning a loading at 1 removes one parameter and can bias the other loadings and unique variances, with no diagnostic flagging the loss. Supply a length-d character vector (one anchor species per axis, pinned at +1; NA skips an axis) only when you want that restriction. Use NULL to auto-pick anchors as the first species of the group that loads on each axis whose row index is on or below the diagonal (row >= axis). That placement is required because the engine can pin only the lower triangle of Lambda. An explicit or auto-picked anchor in the strict upper triangle is an error.

axis_labels

Optional length-d character vector for the matrix column names. Defaults to c("LV1", "LV2", ...).

Value

An length(species) by d numeric matrix with NA entries (estimated), 0 entries (pinned to zero), and 1 entries (pinned at an opt-in anchor), ready to pass to gllvmTMB() as lambda_constraint = list(unit = M).

Details

This is the recommended starting point for confirmatory JSDMs where prior knowledge takes the form "species in group A respond to gradient 1, species in group B respond to gradient 2, ...". The engine parameterises Lambda as lower-triangular, so an axis-j anchor must fall on species row i >= j; otherwise the pin has no packed slot and would be dropped. Auto-anchors (anchors = NULL) honour that rule. For free-form constraint patterns (psychometric CFA, idiosyncratic species-by-species pins), build the matrix directly; for purely statistical identification scaffolding when no biology is in play, see suggest_lambda_constraint().

See also

suggest_lambda_constraint() for the lower-level statistical identification scaffold, gllvmTMB() for the lambda_constraint argument.

Examples

species <- c(paste0("A_", 1:3), paste0("B_", 1:3), paste0("C_", 1:4))
group   <- c(rep("A", 3), rep("B", 3), rep("C", 4))

# Group A loads on axis 1; group B loads on axis 2; group C is free.
M <- confirmatory_lambda(
  species  = species,
  group    = group,
  d        = 2L,
  loads_on = list(A = 1L, B = 2L)
)
M
#>     LV1 LV2
#> A_1  NA   0
#> A_2  NA   0
#> A_3  NA   0
#> B_1   0  NA
#> B_2   0  NA
#> B_3   0  NA
#> C_1  NA  NA
#> C_2  NA  NA
#> C_3  NA  NA
#> C_4  NA  NA