Skip to contents

Generate skew-normal latent site effects

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

Draw J standardized site effects from the Azzalini skew-normal distribution, then apply the shared Layer 1 location-scale wrapper to produce \(\tau_j = \tau + X_j\boldsymbol{\beta} + \sigma_\tau\,z_j\). Reach for the skew-normal when you want a unimodal-but-asymmetric shape — for example, when site-level treatment effects show a heavier positive (or negative) tail than Gaussian.

Usage

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

slant

Numeric. Azzalini skewness parameter \(\alpha\). Required — no default. Positive values produce a right-skewed shape; negative values, left-skewed. Typical applied values: 2 (modest skew), 5 (pronounced skew). slant = 0 is exactly Gaussian (use gen_effects_gaussian instead). |slant| > 30 triggers a 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 skew-normal residual), tau_j (response-scale effect), plus any covariate columns from data.

Details

The package draws \(Y_j \sim \mathrm{SN}(\xi=0, \omega=1, \alpha = \mathrm{slant})\) and standardizes to \(z_j = (Y_j - \mu_Y) / \sigma_Y\), where \(\mu_Y = \delta\sqrt{2/\pi}\) and \(\sigma_Y = \sqrt{1 - 2\delta^2/\pi}\) with \(\delta = \mathrm{slant} / \sqrt{1 + \mathrm{slant}^2}\). The standardization satisfies the unit-variance Layer 1 convention.

slant = 0 reduces to Gaussian (and emits a hint to switch to gen_effects_gaussian). Large |slant| (> 30) approaches the half-normal limit and emits a numerical-stability warning.

Requires the sn package (a Suggests dependency). The function calls sn::rsn() and aborts with a friendly install hint if sn is unavailable.

For the broader catalog and decision rubric, see the G-distribution catalog and standardization vignette.

References

Azzalini, A. (1985). A class of distributions which includes the normal ones. Scandinavian Journal of Statistics, 12(2), 171–178.

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 symmetric baseline; gen_effects_studentt for symmetric heavy tails; gen_effects_ald for an alternative asymmetric shape with exponential tails; rsn for the underlying skew-normal 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_studentt(), gen_effects_user()

Examples

if (requireNamespace("sn", quietly = TRUE)) {
  # Modest right-skew.
  gen_effects_skewn(J = 10L, slant = 2)

  # Pronounced left-skew.
  gen_effects_skewn(J = 50L, slant = -5, sigma_tau = 0.15)
}
#> # A tibble: 50 × 3
#>    site_index     z_j   tau_j
#>         <int>   <dbl>   <dbl>
#>  1          1 -0.136  -0.0205
#>  2          2  0.607   0.0911
#>  3          3 -0.515  -0.0772
#>  4          4  1.35    0.203 
#>  5          5  0.774   0.116 
#>  6          6 -0.296  -0.0444
#>  7          7  0.156   0.0234
#>  8          8 -0.399  -0.0598
#>  9          9 -0.428  -0.0642
#> 10         10 -0.0980 -0.0147
#> # ℹ 40 more rows