Skip to contents

Confidence Eye plot for per-species loading uncertainty

Source: R/plot-loadings-confidence-eye.R
plot_loadings_confidence_eye.Rd

A bar-and-whisker visualisation of the entries of Lambda with point estimates and Wald (or other-method) confidence intervals from loading_ci(). Default rendering uses the "Confidence Eye" contract: a pale CI region (geom_linerange) and a hollow point estimate (geom_point, shape = 21, fill white) so the visual weight rests on the uncertainty rather than the point.

Usage

plot_loadings_confidence_eye(
  fit,
  level = c("unit", "unit_obs"),
  method = "wald",
  conf_level = 0.95,
  null_region = NULL,
  sort_by = c("trait_order", "magnitude"),
  ylim = NULL
)

Arguments

fit

A multivariate gllvmTMB() fit, OR a data frame already produced by loading_ci() / flag_unreliable_loadings().

level, method, conf_level

Forwarded to loading_ci() when fit is a fit object. Ignored when fit is already a loading_ci() data frame.

null_region

Optional length-2 numeric drawn as a shaded "biologically negligible" band so the reader can tell at a glance which CIs sit outside it. If supplied, also colours points by reliability via flag_unreliable_loadings(). Default NULL (no band drawn).

sort_by

Character, one of "trait_order" (the order of the trait factor, the default) or "magnitude". Note "magnitude" applies a single global trait ordering keyed by each trait's largest absolute loading across axes; the shared discrete x-axis cannot reorder traits within individual facets.

ylim

Optional length-2 numeric vector clipping the y-axis via coord_cartesian(). Useful when one degenerate loading estimate would otherwise blow out the scale and crush the rest. Default NULL (no clipping).

Value

A ggplot object.

Details

The closest published precedent for an uncertainty-aware per-species loading display in JSDM is the site-score uncertainty plot of Hoegh & Roberts (2020, doi:10.1002/ece3.5752), but that targets site scores rather than species loadings. To my knowledge no equivalent plot of per-species Lambda uncertainty exists in the ML/TMB JSDM lineage (gllvm, sjSDM, ecoCopula).

See also

loading_ci(), flag_unreliable_loadings().

Examples

if (FALSE) { # \dontrun{
plot_loadings_confidence_eye(fit, level = "unit",
                             null_region = c(-0.1, 0.1))
} # }