Pre-fit Design-Support Diagnostics

Diagnose the design before invoking Stan

Many modeling failures can be identified from the declared design itself. Version 0.2.0 adds four reporting audits that run before MCMC:

audit_missingness_structure();
audit_fixed_effect_design();
audit_random_effects_support(); and
audit_design_support().

They do not impute, exclude, drop predictors, or simplify random effects.

simulation <- simulate_hierarchical_binary_data(
  n_participants = 12,
  trials_per_participant = 10,
  n_items = 6,
  random_slope_sd = 0,
  seed = 11
)

contract <- create_model_contract(
  family = "binary",
  outcome_col = "selected",
  participant_col = "participant_id",
  item_col = "item_id",
  trial_col = "trial_id",
  condition_col = "condition",
  predictors = "trial_covariate"
)

Missingness is described, not repaired

with_missing <- simulation$data
with_missing$trial_covariate[c(3, 17, 41)] <- NA_real_

missingness <- audit_missingness_structure(
  with_missing,
  contract
)
missingness
#> <gp3bayes_missingness_audit>
#>   Status: pass
#>   Rows: 120
#>   Missing cells: 3
plot(missingness)

Fixed-effect geometry

The fixed-effects audit reports design-matrix rank, singular values, a condition-number screen, invariant columns, and leverage. These quantities are warning signals about the declared numerical design; they do not determine a scientifically preferred model.

fixed_design <- audit_fixed_effect_design(
  simulation$data,
  contract
)
fixed_design
#> <gp3bayes_fixed_effect_design_audit>
#>   Status: review
#>   Rank: 3/3
#>   Condition number: 2.6181
#>   High-leverage rows: 3
plot(fixed_design)

Repetition, crossing and random slopes

random_support <- audit_random_effects_support(
  simulation$data,
  contract
)
random_support
#> <gp3bayes_random_effects_support_audit>
#>   Status: pass
#>               component status
#>  participant_repetition   pass
#>           item_crossing   pass
#>    random_slope_support   pass
plot(random_support)

One combined preflight

design <- audit_design_support(
  simulation$data,
  contract,
  separation = FALSE,
  strict_readiness = TRUE
)
design
#> <gp3bayes_design_support_audit>
#>   Status: review
#>               component       status
#>      standard_readiness         pass
#>        strict_readiness         pass
#>             missingness         pass
#>     fixed_effect_design       review
#>  random_effects_support         pass
#>              separation not_assessed
#>   Automatic model changes: FALSE
plot(design)

For binary models, a fixed-effects separation screen can also be requested when detectseparation is installed:

audit_design_support(
  simulation$data,
  contract,
  separation = TRUE
)

A review or fail flag is a prompt for methodological inspection. It is not an automatic instruction to remove data or alter the prespecified model.