Fit a GLLVM from a wide unit × trait matrix

Convenience wrapper that lets users supply a wide unit × trait response matrix Y (rows = units, columns = traits) and an optional unit-level predictor data frame X. Pivots to long format internally and dispatches to gllvmTMB().

Usage

gllvmTMB_wide(
  Y,
  X = NULL,
  d = 2,
  family = gaussian(),
  phylo_vcv = NULL,
  formula_extra = NULL,
  weights = NULL,
  ...
)

Arguments

Y

A n_units × n_traits numeric matrix of responses (presence / absence, abundance, continuous measurements, item scores). Rows must be unique units; columns must be unique traits.

X

Optional n_units × n_predictors data frame of unit-level predictors. Row order must match Y.

d

Integer; the number of latent factors. Default 2.

family

A family object (default gaussian()); for presence/absence matrices use binomial().

phylo_vcv

Optional n_traits x n_traits phylogenetic correlation matrix (rownames must match colnames of Y). When supplied, a phylo_latent() term with d factors is added. For the canonical site × species use case the "traits" are species, so this is the species-level phylogenetic correlation.

formula_extra

Optional formula RHS to splice into the fixed effects, e.g. ~ env_temp + env_precip. Defaults to ~ 1.

weights

Optional per-cell observation weights, parallel to Y. At wide level the semantic is always lme4 / glmmTMB-style: each cell's log-likelihood contribution is multiplied by its weight. Accepted shapes are normalised to the same long-format vector used by gllvmTMB() and the wide data-frame traits() path:

• NULL (default): unit weights; byte-identical to the no-weight fit.

• numeric(nrow(Y)): row vector. Each cell (i, j) inherits weights[i] for every column j. The common case (per-row sample size, per-individual study weight, per-site sampling intensity).

• matrix of dim(Y): per-cell weights. NA cells in Y MUST be NA in weights (the only meaningful alignment); a mismatch errors. Use this for meta-analytic / per-cell-uncertainty weighting.

• single positive numeric (length 1): broadcast to all cells. Disambiguation when nrow(Y) == ncol(Y): length(dim(weights)) decides — NULL (1-d) → vector, row-broadcast; c(n, m) (2-d) → per-cell. Values must be non-negative and finite (NA-aligned cells excepted). For binomial trial-count semantics use the long-format API (gllvmTMB() with weights = n_trials) instead.

...

Passed to gllvmTMB().

Value

A gllvmTMB_multi fit. The column dimension of Y is exposed as the "trait" axis of the engine (so extract_ordination() returns the trait loadings). For the site × species special case the columns are species, and the loadings are species loadings; the same machinery returns trait loadings for individual × trait morphometrics, study loadings for paper × outcome meta-analysis, etc.

Details

The "unit × trait" framing is generic: site × species (joint species distribution modelling), individual × trait (morphometrics / behavioural syndromes), species × trait (phylogenetic comparative), paper × outcome (meta-analysis), or any similar layout. The function does not assume the ecological special case; it is the unified matrix-in entry point for the stacked-trait GLLVM engine.

Deprecation

gllvmTMB_wide() is soft-deprecated as of gllvmTMB 0.2.0. The recommended replacement is gllvmTMB() with the traits() LHS marker, which is more general (formula-native predictors, full covariance grammar, mixed-family fits) and matches the formula-first idiom used by lme4, glmmTMB, brms, drmTMB.

Migration:

## Old:
fit <- gllvmTMB_wide(Y, X = X_df, d = 2,
                     formula_extra = ~ env_temp + env_precip)

## New:
df_wide <- cbind(data.frame(unit = rownames(Y)),
                 as.data.frame(Y), X_df)
fit <- gllvmTMB(
  traits(<colnames of Y>) ~ 1 + env_temp + env_precip +
    latent(1 | unit, d = 2),
  data = df_wide,
  unit = "unit"
)

Per-cell weight matrices (the one path gllvmTMB_wide() uniquely supports) remain available via the long-format API by passing a long-format weights column aligned with (unit, trait) rows. See docs/design/02-data-shape-and-weights.md.

See also

gllvmTMB() for the recommended formula-API entry point (long format or wide data frames via traits() LHS sugar); extract_Sigma() for post-fit covariance summaries; extract_ordination() for scores and loadings. The source-tree contract is docs/design/02-data-shape-and-weights.md.