Skip to contents

Generate Dirichlet-process-mixture latent site effects

Source: R/layer1-gen_effects_dpm.R
gen_effects_dpm.Rd

Draw J latent site effects from a Dirichlet-process mixture. The current release ships only the user-callback bridge for this shape — to use true_dist = "DPM" you must supply a g_fn bridge that draws DPM samples (typically fitted by an external package such as dirichletprocess or the JAGS / Stan posterior of a DPM model). Calling without a g_fn aborts with an install-hint pointing to the user-callback path.

Usage

gen_effects_dpm(
  J,
  tau = 0,
  sigma_tau = 0.2,
  theta_G = list(),
  formula = NULL,
  beta = NULL,
  data = NULL,
  g_fn = NULL,
  g_returns = c("standardized", "raw"),
  audit_g = TRUE
)

Arguments

J

Integer. Number of sites.

tau

Numeric. Grand mean on the response scale. Default 0.

sigma_tau

Numeric (\(\ge 0\)). Between-site standard deviation on the response scale. Default 0.20.

theta_G

Named list. When a g_fn bridge is supplied, this list is forwarded to the bridge as extra arguments (after J). Default list().

formula

One-sided formula for site-level covariates, or NULL.

beta

Numeric coefficient vector matching formula, or NULL.

data

A data.frame with the predictors named in formula, or NULL.

g_fn

Optional DPM bridge callback with signature function(J, ...). When NULL, the function aborts with an install-hint pointing to the user-callback route.

g_returns

Character. Bridge convention — "standardized" (Convention A, default) or "raw" (Convention B). See gen_effects_user for the contract.

audit_g

Logical. Whether to validate (Convention A only) that the bridge's draws meet the unit-moment contract. Default TRUE.

Value

A tibble with one row per site and columns site_index, z_j, tau_j, plus any covariate columns from data. Returned only when a g_fn bridge is supplied; otherwise the function aborts.

Details

DPM as a built-in shape is on the roadmap but currently routes through the user-callback convention. When g_fn is supplied, this function delegates to gen_effects_user with theta_G forwarded as g_args. All Convention A / Convention B semantics, the audit pass, and the cross-link to the Custom G vignette apply identically.

Typical workflow for the bridge: fit a DPM offline (e.g., via dirichletprocess::DirichletProcessGaussian), wrap a finite-sample draw in a g_fn(J, ...) closure that returns standardized residuals (Convention A), and pass that closure to sim_multisite() / sim_meta() via g_fn and true_dist = "DPM" (or just "User" — the same code path).

For the formal callback contract, see the Custom G distributions vignette.

References

Lee, J., Che, J., Rabe-Hesketh, S., Feller, A., & Miratrix, L. (2025). Improving the estimation of site-specific effects and their distribution in multisite trials. Journal of Educational and Behavioral Statistics, 50(5), 731–764. doi:10.3102/10769986241254286 .

See also

gen_effects_user for the underlying user-callback pathway that the bridge routes through; gen_effects for the dispatcher and the full eight-shape catalog; the M5 Custom G distributions vignette.

Other family-effects: gen_effects(), gen_effects_ald(), gen_effects_gaussian(), gen_effects_mixture(), gen_effects_pmslab(), gen_effects_skewn(), gen_effects_studentt(), gen_effects_user()

Examples

# Bridge a Gaussian DPM draw (placeholder — substitute a real DPM sampler).
gen_effects_dpm(
  J = 10L,
  g_fn = function(J) rnorm(J),
  audit_g = FALSE
)
#> # A tibble: 10 × 3
#>    site_index     z_j    tau_j
#>         <int>   <dbl>    <dbl>
#>  1          1  0.0708  0.0142 
#>  2          2 -1.54   -0.307  
#>  3          3  0.454   0.0908 
#>  4          4  0.874   0.175  
#>  5          5 -1.30   -0.260  
#>  6          6 -1.08   -0.216  
#>  7          7 -1.13   -0.227  
#>  8          8  0.0226  0.00452
#>  9          9 -0.0215 -0.00429
#> 10         10 -0.279  -0.0558