Screen candidate responses before fitting a gllvmTMB model

screen_gllvmTMB() is a formula-aware pre-fit screen. It summarises response and formula conditions before fitting a stacked-trait GLLVM. The screen is advisory: it does not fit the model, remove traits, choose a latent rank, prove identifiability, or guarantee convergence. Binary/binomial screening is implemented. Non-binary modules, optional comparator checks, and high-dimensional benchmarks are not currently part of this function.

Usage

screen_gllvmTMB(
  formula,
  data,
  family,
  unit = NULL,
  trait = "trait",
  weights = NULL,
  missing = miss_control(),
  control = screen_control()
)

Arguments

formula: A gllvmTMB() formula. Wide data can use traits() on the left-hand side; long data should use a response column on the left-hand side plus trait =.
data: A data frame.
family: A response family. Version 1 screens single-family binomial() fits with logit, probit, or cloglog links.
unit: Optional unit/grouping column. If omitted, the first covariance-structure grouping column is used when available.
trait: Trait column for long data. Wide traits() calls create this column internally.
weights: Optional weights vector, with the same binomial trial-count semantics as gllvmTMB() for long-format binomial fits.
missing: Missing-data control; defaults to miss_control().
control: A screen_control() object.

Value

A gllvmTMB_screen object. Use screen_table() to extract report-ready tables.

Details

The first implemented module covers binomial traits. It distinguishes Bernoulli responses from multi-trial binomial responses, reports the relevant denominators, and flags constants, sparse minority outcomes, duplicate or near-duplicate binary traits, rank-deficient fixed-effect designs, and grouping/rank conditions that should be inspected before interpretation. In systematic maps, a trait may be a content item or indicator. In a binary JSDM, a trait may be a species presence-absence response. Rare or constant species are flagged for inspection and possible sensitivity analysis, not automatically removed.

References

Albert A, Anderson JA (1984). On the existence of maximum likelihood estimates in logistic regression models. Biometrika 71:1–10. doi:10.1093/biomet/71.1.1.

Peduzzi P, Concato J, Kemper E, Holford TR, Feinstein AR (1996). A simulation study of the number of events per variable in logistic regression analysis. Journal of Clinical Epidemiology 49:1373–1379. doi:10.1016/S0895-4356(96)00236-3.

Vittinghoff E, McCulloch CE (2007). Relaxing the rule of ten events per variable in logistic and Cox regression. American Journal of Epidemiology 165:710–718. doi:10.1093/aje/kwk052.

Chalmers RP (2012). mirt: A multidimensional item response theory package for the R environment. Journal of Statistical Software 48(6):1–29. doi:10.18637/jss.v048.i06.

Examples

df <- data.frame(
  study = factor(seq_len(12)),
  a = c(rep(1, 10), 0, 0),
  b = c(rep(1, 10), 0, 0),
  c = rep(c(0, 1), 6)
)
# The wrapper keeps the rendered example focused on the screen tables;
# inspect warnings in interactive work.
scr <- suppressWarnings(screen_gllvmTMB(
  traits(a, b, c) ~ 1 + latent(1 | study, d = 2),
  data = df,
  unit = "study",
  family = binomial()
))
screen_table(scr, "traits")
#>   trait response_mode status severity n_obs n_valid n_units n_success n_failure
#> 1     a     bernoulli   WARN   strong    12      12      12        10         2
#> 2     b     bernoulli   WARN   strong    12      12      12        10         2
#> 3     c     bernoulli   WARN moderate    12      12      12         6         6
#>   total_trials prevalence minority_rate minority_count info_fraction invalid_n
#> 1           12  0.8333333     0.1666667              2     0.5555556         0
#> 2           12  0.8333333     0.1666667              2     0.5555556         0
#> 3           12  0.5000000     0.5000000              6     1.0000000         0
#>    action                                           message
#> 1 inspect the minority outcome has very few observed trials
#> 2 inspect the minority outcome has very few observed trials
#> 3 inspect      the minority outcome has few observed trials
screen_table(scr, "recommendations")
#>   scope status             action trait
#> 1 trait   WARN            inspect     a
#> 2 trait   WARN            inspect     b
#> 3 trait   WARN            inspect     c
#> 4  pair   FAIL collapse_or_recode a / b
#> 5  pair   WARN            inspect a / c
#> 6  pair   WARN            inspect b / c
#>                                             evidence
#> 1  the minority outcome has very few observed trials
#> 2  the minority outcome has very few observed trials
#> 3       the minority outcome has few observed trials
#> 4 the two traits are exact duplicates on paired rows
#> 5  the two traits are near-duplicates on paired rows
#> 6  the two traits are near-duplicates on paired rows
#>                                                           model_implication
#> 1 inspect coding, missingness, and latent-response inclusion before fitting
#> 2 inspect coding, missingness, and latent-response inclusion before fitting
#> 3 inspect coding, missingness, and latent-response inclusion before fitting
#> 4  inspect whether both traits should enter the first latent-response block
#> 5  inspect whether both traits should enter the first latent-response block
#> 6  inspect whether both traits should enter the first latent-response block