View source: R/simulate_bias.R
| simulate_bias | R Documentation |
Quantify fixed-effect estimation error under a specified conditional generating model, re-estimating covariance and persistence parameters for every response.
simulate_bias(
model,
data,
nsim = 100,
beta = NULL,
k_list = NULL,
generator = NULL,
centered_errors = is.null(generator),
refit_control = list(),
verbose = FALSE
)
model |
A converged GPvam fit created with version 3.4-0 or later. |
data |
The original input data frame, including missing-score rows. Student, teacher and year keys, row names, observed-score pattern, fitted responses and fixed-effect design must match the supplied fit. |
nsim |
Number of independent simulations, an integer at least 2. |
beta |
Generating fixed-effect vector, defaulting to the fitted vector. Named vectors must have exactly the fitted names and order. |
k_list |
Named list of contrast vectors in the fitted coefficient order. A single numeric vector is also accepted. NULL examines every coefficient. |
generator |
Optional function taking model and replicate, returning finite numeric vectors random_effects and residual_errors. Their orders are those of model$eta.hat and model$observation, respectively. The default holds fitted random effects fixed and draws centered Gaussian residuals with the original fitted residual covariance on observed scores. |
centered_errors |
Logical declaration that generating residuals have mean zero, default TRUE for the default generator and FALSE otherwise. |
refit_control |
Named list with optional max.iter.EM and tol1 overrides. Defaults are the original fit's resolved values. Model structure, formula, and ML/REML choice cannot be changed. Hessians are not recomputed. |
verbose |
Print one progress line per replicate. |
All R-side persistence types (GP, rGP, VP, CP, ZP) and the supported G-side GP model are handled. The original design, score-missingness pattern, and known teacher assignments on missing-score rows are fixed. Missing scores are not imputed; their known assignments can still contribute to later scores. For R-side models the original within-student residual correlations are retained. G-side residuals have the fitted year-specific variances; the default also holds the fitted student random effects fixed, along with teacher effects. These fixed predictions are shrunken; refitted covariance estimates can differ systematically from the original fit as part of this conditional target. R-side defaults redraw within-student dependence through residuals, whereas G-side defaults hold student effects fixed, so their targets differ.
Responses are generated as y_s = X beta + h_s + e_s, where h_s = Z_0 eta_s uses the ORIGINAL fitted random-effect design. Every refit uses the same formula, persistence type, student side and ML/REML setting. For VP, the persistence multipliers and hence the refitted design Z_s may change. With fitted GLS map W_s, Alignment is k'W_s h_s, Residual is k'W_s e_s, and Total is their sum. Estimation_Error records k'(beta_hat_s - beta), and the pointwise decomposition is checked numerically. Internal_Diagnostic is k'W_s Z_s eta_hat_s, using the REFITTED design and effects; it is not the generated latent contribution. Alignment_Teacher and Alignment_Student split Alignment for G-side fits. The student term is zero for R-side fits.
If centered_errors is TRUE, Residual_CV is k'(W_s - W_0)e_s, where W_0 uses the original fitted covariance. Its expectation equals that of Residual because W_0 is fixed and the declared residual mean is zero. Total_CV is Alignment + Residual_CV. These paired control variates often reduce Monte Carlo uncertainty, but variance reduction is not guaranteed. Raw contributions are always retained. MCSE is the empirical standard deviation of the actual replicate values divided by the square root of the successful replicate count.
Simulations are sequential and use R's RNG; use set.seed(). Custom generators must produce independent replicates with finite variances for this MCSE interpretation. A generator error or invalid return aborts the entire call; completed replicates are not returned after this contract violation. Refit error and nonconvergence rows remain explicit with missing contributions. After failures, raw summaries describe successful refits only; ALL control-variate summary means and MCSEs are withheld, because selection of successful refits can invalidate their equal-expectation argument. An Ill_Conditioned flag records a covariance block with eigenvalue ratio below 1e-8 or a nonpositive eigenvalue; those converged refits are retained. This flag does not detect every variance boundary (in particular, a tiny scalar variance has ratio one). GLS and decomposition checks use a tolerance of 1e-6 times the larger of one and the absolute values being compared; discrepancies are retained in fit_status, and values beyond tolerance make the replicate a failure.
This is a conditional sensitivity experiment under chosen generating values, not an estimate of unconditional population bias or a calibrated bias test. It does not generate an endogenous classroom-assignment or stochastic-covariate mechanism. No automatic coefficient adjustment is supplied. A custom generator changes latent/error draws at a fixed design; stochastic designs require an external joint generating and refitting workflow.
The original data are required explicitly and are never recovered by evaluating the stored call. Older fitted objects must be refitted once with the current GPvam to obtain validated simulation metadata. Formula dependence on y is rejected, as are formula variables absent from data. Use the same collation locale as for the original fit; differing locales are rejected before refits. Output contains coefficient-level summaries and statuses, not input rows, generated response vectors, fitted objects, or original identifiers.
A list of class GPvam_simulation with summary, replicates, fit_status, counts, beta, original_diagnostic, centered_errors, generator_type, and model_spec. Use qualified function names GPvam::simulate_bias and mixedbiastest::simulate_bias when both are attached.
GPvam, bias.test.custom
data(vam_data)
fit <- GPvam(vam_data, ~as.factor(year) + cont_var + 0,
persistence = "CP", verbose = FALSE)
set.seed(20261022)
# Two draws illustrate the API; use more to obtain useful Monte Carlo precision.
sim <- simulate_bias(fit, vam_data, nsim = 2)
sim$summary
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.