Skip to contents

Flag loadings whose CI overlaps a "biologically negligible" region

Source: R/loading-ci.R
flag_unreliable_loadings.Rd

A simple decision aid in the spirit of Zientek & Thompson (2007, doi:10.3758/BF03193163): given per-entry CIs on Lambda, flag the entries whose conf_level confidence interval does not exclude a user-supplied "null region" — a band around zero considered biologically negligible on the interval's recorded loading_scale. Loadings flagged as unreliable = TRUE are the ones for which the data do not provide evidence that the species responds non-trivially to the axis.

Usage

flag_unreliable_loadings(
  fit,
  null_region = c(-0.1, 0.1),
  level = "unit",
  method = "wald",
  conf_level = 0.95,
  loading_scale = NULL
)

Arguments

fit

A multivariate gllvmTMB() fit, or a data frame already produced by loading_ci().

null_region

Length-2 numeric, sorted ascending. The "negligible" band. Defaults to c(-0.1, 0.1).

level, method, conf_level, loading_scale

Forwarded to loading_ci() when fit is a fit object. Ignored when fit is already a loading_ci() data frame, except that an explicitly supplied loading_scale must match the frame's scale.

Value

The loading_ci() data frame with one extra logical column unreliable: TRUE if the CI overlaps null_region, FALSE if it lies entirely outside, NA for pinned entries.

Details

Pinned entries (set explicitly by lambda_constraint) are reported with unreliable = NA because no inference is being made about them.

See also

loading_ci().

Examples

set.seed(1)
# Eight traits measured twice on each of 100 units (e.g. sites).
# Odd-numbered traits respond to one latent gradient and even-numbered
# traits to another; trait_7 responds only weakly.
Lambda <- cbind(c(0.9, 0, 0.7, 0, 0.6, 0, 0.15, 0),
                c(0, 0.9, 0, 0.8, 0, 0.6, 0, 0.5))
sim <- simulate_unit_trait(n_units = 100, n_obs_per_unit = 2,
                           n_traits = 8, Lambda_B = Lambda,
                           psi_B = 0.5, sigma2_eps = 0.3)
# Confirmatory fit: odd traits load only on axis 1, even traits only on
# axis 2 (see ?loading_ci).
M <- confirmatory_lambda(species = levels(sim$data$trait),
                         group = rep(c("A", "B"), times = 4), d = 2,
                         loads_on = list(A = 1, B = 2),
                         anchors = c(NA, NA))
fit <- gllvmTMB(value ~ 0 + trait +
                  latent(0 + trait | unit, d = 2, unique = TRUE),
                data = sim$data, trait = "trait", unit = "unit",
                lambda_constraint = list(unit = M))

# A loading is flagged unreliable when its 95% interval reaches into
# the band of negligible values, here -0.1 to 0.1. Fixed (pinned)
# entries get NA because nothing is inferred about them.
fl <- flag_unreliable_loadings(fit, level = "unit",
                               null_region = c(-0.1, 0.1))
fl[, c("trait", "axis", "estimate", "lower", "upper", "unreliable")]
#>      trait axis  estimate     lower     upper unreliable
#> 1  trait_1  LV1 0.7382623 0.4496835 1.0268410      FALSE
#> 2  trait_2  LV1 0.0000000 0.0000000 0.0000000         NA
#> 3  trait_3  LV1 0.8363961 0.5211830 1.1516093      FALSE
#> 4  trait_4  LV1 0.0000000 0.0000000 0.0000000         NA
#> 5  trait_5  LV1 0.5400703 0.2926996 0.7874410      FALSE
#> 6  trait_6  LV1 0.0000000 0.0000000 0.0000000         NA
#> 7  trait_7  LV1 0.2327312 0.0224045 0.4430579       TRUE
#> 8  trait_8  LV1 0.0000000 0.0000000 0.0000000         NA
#> 9  trait_1  LV2 0.0000000 0.0000000 0.0000000         NA
#> 10 trait_2  LV2 0.9737637 0.7324758 1.2150517      FALSE
#> 11 trait_3  LV2 0.0000000 0.0000000 0.0000000         NA
#> 12 trait_4  LV2 0.6363071 0.4153120 0.8573021      FALSE
#> 13 trait_5  LV2 0.0000000 0.0000000 0.0000000         NA
#> 14 trait_6  LV2 0.5602642 0.3451783 0.7753502      FALSE
#> 15 trait_7  LV2 0.0000000 0.0000000 0.0000000         NA
#> 16 trait_8  LV2 0.5409371 0.3612139 0.7206604      FALSE

# The same check on a table from loading_ci(), here on the standardized
# (correlation) scale, treating values between -0.2 and 0.2 as
# negligible.
ci_std <- loading_ci(fit, loading_scale = "standardized")
fl_std <- flag_unreliable_loadings(ci_std, null_region = c(-0.2, 0.2))
fl_std[!fl_std$pinned, c("trait", "axis", "estimate", "unreliable")]
#>      trait axis  estimate unreliable
#> 1  trait_1  LV1 0.6859064      FALSE
#> 3  trait_3  LV1 0.7385727      FALSE
#> 5  trait_5  LV1 0.5587020      FALSE
#> 7  trait_7  LV1 0.3033749       TRUE
#> 10 trait_2  LV2 0.8722014      FALSE
#> 12 trait_4  LV2 0.6400415      FALSE
#> 14 trait_6  LV2 0.5870137      FALSE
#> 16 trait_8  LV2 0.6860735      FALSE