Skip to contents

Generate Student-t latent site effects

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

Draw J standardized site effects from a Student-t distribution with degrees of freedom nu (rescaled to unit variance), then apply the shared Layer 1 location-scale wrapper to produce \(\tau_j = \tau + X_j\boldsymbol{\beta} + \sigma_\tau\,z_j\). Reach for Student-t when you want heavier tails than Gaussian — for example, when modeling a robustness check against extreme effects, or when the empirical literature you are calibrating to shows kurtosis above 3.

Usage

gen_effects_studentt(
  J,
  tau = 0,
  sigma_tau = 0.2,
  nu,
  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.

nu

Numeric (> 2). Degrees of freedom. Required — no default. Typical values: 5 (modest heavy tails), 10 (mild departure from Gaussian). nu < 4 triggers a kurtosis-stability warning.

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 Student-t residual), tau_j (response-scale effect), plus any covariate columns from data.

Details

The unscaled draw is \(T_j \sim t_\nu\); the package rescales by \(\sqrt{(\nu - 2)/\nu}\) so that \(z_j\) has unit variance, matching the Layer 1 standardization convention (see gen_effects). Degrees of freedom nu must be strictly greater than 2 for the rescaling to be well-defined; the function emits a warning when nu < 4 because kurtosis is non-finite there and Monte Carlo moment checks may be noisy.

Tail-heaviness decreases as nu grows: nu = 5 gives kurtosis 6 (modest heavy tails), nu = 10 gives kurtosis ≈ 3.75 (close to Gaussian), nu = 30 is essentially Gaussian for practical purposes. Pick nu to match the literature you are calibrating to.

For the broader catalog and a decision rubric on when to choose a heavier-tailed or asymmetric shape, 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_gaussian for the canonical baseline; gen_effects_skewn for asymmetric heavy tails; rt for the underlying Student-t generator; 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_pmslab(), gen_effects_skewn(), gen_effects_user()

Examples

# Modest heavy tails: nu = 5 gives kurtosis 6.
gen_effects_studentt(J = 10L, nu = 5)
#> # A tibble: 10 × 3
#>    site_index    z_j   tau_j
#>         <int>  <dbl>   <dbl>
#>  1          1  1.16   0.233 
#>  2          2  0.219  0.0437
#>  3          3 -0.708 -0.142 
#>  4          4 -0.598 -0.120 
#>  5          5  1.98   0.397 
#>  6          6  3.18   0.636 
#>  7          7  0.316  0.0632
#>  8          8 -0.282 -0.0563
#>  9          9  0.852  0.170 
#> 10         10 -0.646 -0.129 

# Larger draw, tighter tails (nu = 10).
gen_effects_studentt(J = 50L, tau = 0.2, sigma_tau = 0.15, nu = 10)
#> # A tibble: 50 × 3
#>    site_index    z_j  tau_j
#>         <int>  <dbl>  <dbl>
#>  1          1 -0.338 0.149 
#>  2          2  0.708 0.306 
#>  3          3 -1.20  0.0200
#>  4          4 -0.933 0.0600
#>  5          5 -0.113 0.183 
#>  6          6  0.987 0.348 
#>  7          7  0.220 0.233 
#>  8          8 -1.14  0.0292
#>  9          9 -0.435 0.135 
#> 10         10 -0.176 0.174 
#> # ℹ 40 more rows