Skip to contents

Generate point-mass-plus-slab latent site effects

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

Draw J standardized site effects from a mixed measure: a point mass at zero with probability pi0 and a zero-centered continuous slab with probability 1 - pi0. Apply the shared Layer 1 location-scale wrapper to produce \(\tau_j = \tau + X_j\boldsymbol{\beta} + \sigma_\tau\,z_j\). Reach for this shape when a fraction of sites have null effects (no treatment effect, by design or by selection) and the rest have a continuous effect distribution.

Usage

gen_effects_pmslab(
  J,
  tau = 0,
  sigma_tau = 0.2,
  pi0,
  slab_shape = c("Gaussian", "Laplace"),
  mu_slab = 0,
  sigma_slab = 1,
  formula = NULL,
  beta = NULL,
  data = NULL
)

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.

pi0

Numeric in (0, 1). Point-mass probability at zero. Required — no default. pi0 = 0.2 puts 20% of sites at exactly zero; pi0 = 0.5 is balanced. Endpoints are refused.

slab_shape

Character. Slab family — "Gaussian" (default) or "Laplace". Laplace gives a sharper peak at zero with exponential tails; Gaussian is smoother.

mu_slab

Numeric. Raw slab location before standardization. Default 0. Most users leave this at the default.

sigma_slab

Numeric (> 0). Raw slab SD before standardization. Default 1. Most users leave this at the default; the package automatically rescales to the unit-variance contract.

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.

Value

A tibble with one row per site and columns site_index (integer 1:J), z_j (unit-variance point-mass-slab residual; exactly 0 with probability pi0), tau_j (response-scale effect), plus any covariate columns from data.

Details

The slab is centered at zero and rescaled so that the total residual variance equals 1: a draw \(z_j\) comes from a point mass at 0 with probability pi0 and from a zero-mean slab with SD \(1/\sqrt{1 - \mathrm{pi0}}\) with probability 1 - pi0. The slab shape is either Gaussian (default) or Laplace, controlled by slab_shape. The pre-standardization slab parameters mu_slab and sigma_slab are reserved for raw-form specification but are normalized to the unit-variance contract before the draw lands in z_j — applied users can leave them at their defaults.

For the broader catalog and decision rubric, see the G-distribution catalog and standardization 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 for the dispatcher and the full eight-shape catalog; gen_effects_mixture for a related two-component mixture shape (without a point mass); gen_effects_gaussian for the unimodal baseline; the M2 G-distribution catalog vignette.

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

Examples

# 20% null sites + 80% Gaussian slab.
pms <- gen_effects_pmslab(J = 50L, pi0 = 0.2)
sum(pms$z_j == 0)  # ~ 10 sites with exactly-zero standardized effect
#> [1] 14

# Sharper peak at zero with Laplace slab; 30% null sites.
gen_effects_pmslab(J = 50L, pi0 = 0.3, slab_shape = "Laplace",
                   sigma_tau = 0.15)
#> # A tibble: 50 × 3
#>    site_index    z_j   tau_j
#>         <int>  <dbl>   <dbl>
#>  1          1  1.03   0.154 
#>  2          2  0      0     
#>  3          3 -1.88  -0.281 
#>  4          4  2.38   0.357 
#>  5          5  0      0     
#>  6          6  0.656  0.0984
#>  7          7  0.147  0.0221
#>  8          8  0.543  0.0815
#>  9          9 -0.123 -0.0184
#> 10         10  0.730  0.109 
#> # ℹ 40 more rows