Build a confirmatory lambda_constraint matrix from group membership

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), and one anchor species per axis is pinned at +1 to fix the scale. Groups present in group but absent from loads_on remain free on all axes.

Usage

confirmatory_lambda(
  species,
  group,
  d,
  loads_on,
  anchors = NULL,
  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

Optional length-d character vector; one anchor species per axis (pinned at +1). If NULL (the default), anchors are auto-picked as the first species belonging to the group that loads on each axis. Use NA to skip the anchor on a specific axis.

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 the 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, ...". 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   1   0
#> A_2  NA   0
#> A_3  NA   0
#> B_1   0   1
#> B_2   0  NA
#> B_3   0  NA
#> C_1  NA  NA
#> C_2  NA  NA
#> C_3  NA  NA
#> C_4  NA  NA