Skip to contents

Fit a GLLVM with the Julia engine (GLLVM.jl bridge_fit).

Source: R/julia-bridge.R
gllvm_julia_fit.Rd

Fit a GLLVM with the Julia engine (GLLVM.jl bridge_fit).

Usage

gllvm_julia_fit(
  y,
  family = "gaussian",
  num.lv = 2L,
  N = NULL,
  X = NULL,
  X_lv = NULL,
  coef_fixed = NULL,
  mask = NULL,
  units_are_rows = FALSE,
  ci_method = c("none", "wald", "profile", "bootstrap"),
  ci_level = 0.95,
  ci_nboot = 200L,
  ci_seed = 0L,
  ...
)

Arguments

y

Response matrix, p x n (traits x units), or n x p (set units_are_rows).

family

A family object/string, or a list of them (one per trait -> mixed).

num.lv

Number of latent variables (K).

N

Binomial trials (matrix or scalar), or NULL.

X

Fixed-effect design (p x n x q array), or NULL. Routed for Gaussian and selected one-part non-Gaussian bridge families.

X_lv

Unit-level predictor-informed latent-score design (n x q_lv matrix), or NULL. Routed only for complete Gaussian, Poisson, NB2, Gamma, Beta, and binomial logit/probit/cloglog bridge rows with no fixed-effect X, no response mask, and ci_method in c("none", "wald"). The returned object carries point-estimate alpha_lv, lv_effects, scores_mean, and scores_innovation payloads; for ci_method = "wald" it additionally carries lv_effects_se, lv_effects_lower, and lv_effects_upper, which extract_lv_effects() surfaces as finite std.error, lower, and upper when called with type = "trait_effect". If future bridge payloads include alpha_lv_se, alpha_lv_lower, and alpha_lv_upper, extract_lv_effects() surfaces those on the default axis-effect table. These are bridge-reader Wald payloads, not calibrated coverage claims. Profile/bootstrap X_lv confidence intervals, NB1, ordinal, mixed-family, masked, and fixed-effect-X-plus-X_lv rows remain gated.

coef_fixed

Optional logical vector of length dim(X)[3]. TRUE entries are fixed at zero by the Julia bridge. Most R users should prefer the named Xcoef_fixed argument to gllvmTMB(), which is translated to this positional mask after the expanded fixed-effect design is known.

mask

Optional logical response-observation mask with the same orientation as y; TRUE cells contribute to the likelihood and FALSE cells are ignored. Currently routed for one-part no-X non-Gaussian point fits, with masked no-X CI payloads for Poisson, Bernoulli binomial, NB2, NB1, Beta, and Gamma.

units_are_rows

If TRUE, y is n x p and is transposed to p x n.

ci_method

Confidence-interval route for admitted no-X bridge rows: Gaussian, Poisson, Bernoulli binomial, and grouped-dispersion NB2, NB1, Beta, and Gamma. One of "none" (default), "wald", "profile", or "bootstrap". Response-mask CIs are routed for the same non-ordinal non-Gaussian rows when X = NULL; complete-response fixed-effect-X CIs are routed for Gaussian, Poisson, Bernoulli binomial, NB2, Beta, and Gamma. Predictor-informed X_lv rows admit "wald" confidence intervals. Per-trait ordinal rows, NB1-X rows, mixed-family vectors, profile/bootstrap X_lv rows, and response masks combined with fixed-effect X remain loud gates.

ci_level

Nominal confidence level when ci_method != "none".

ci_nboot

Number of parametric bootstrap replicates when ci_method = "bootstrap".

ci_seed

Seed passed to the Julia bootstrap CI route.

...

Passed to gllvm_julia_setup() (jl_path, julia_home).

Value

A list of class gllvmTMB_julia with the bridge contract fields (loadings, Sigma, correlation, loglik, aic, bic, converged, ...). If ci_method != "none" and the row is admitted, the list also carries flat CI fields consumed by confint().

Examples

if (FALSE) { # \dontrun{
# Requires a local GLLVM.jl install (see [gllvm_julia_setup()]).
# `y` is traits x units (p x n): two Gaussian traits, 40 units, K = 2.
set.seed(1)
y <- matrix(rnorm(2 * 40), nrow = 2)
fit <- gllvm_julia_fit(y, family = "gaussian", num.lv = 2)
fit$loglik
fit$Sigma

# Predictor-informed latent-score means are point-only on the bridge.
rownames(y) <- paste0("trait", seq_len(nrow(y)))
colnames(y) <- paste0("site", seq_len(ncol(y)))
x <- seq(-1, 1, length.out = ncol(y))
fit_lv <- gllvm_julia_fit(
  y,
  family = "gaussian",
  num.lv = 1,
  X_lv = matrix(x, ncol = 1, dimnames = list(colnames(y), "x"))
)
extract_lv_effects(fit_lv)

# Wald confidence intervals for an admitted no-X row:
fit_ci <- gllvm_julia_fit(
  y, family = "gaussian", num.lv = 2, ci_method = "wald"
)
} # }