Skip to contents

Generate asymmetric Laplace latent site effects

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

Draw J standardized site effects from the Yu-Zhang asymmetric Laplace distribution and apply the shared Layer 1 location-scale wrapper to produce \(\tau_j = \tau + X_j\boldsymbol{\beta} + \sigma_\tau\,z_j\). Reach for the asymmetric Laplace when you want a sharp peak at zero with exponential tails — useful for a quantile-flavored shape that contrasts with the smoother skew-normal.

Usage

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

rho

Numeric in (0.05, 0.95). Yu-Zhang quantile / asymmetry parameter. Required — no default. rho = 0.5 is symmetric Laplace; rho = 0.3 skews left; rho = 0.7 skews right. Endpoints 0 and 1 are degenerate; the function refuses values outside (0.05, 0.95).

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

Details

The package draws \(X_j\) from the Yu-Zhang asymmetric Laplace with quantile parameter rho and converted scale, then standardizes via \(z_j = (X_j - \mu_X) / \sigma_X\) where the closed-form moments are \(\mu_X = (1 - 2\rho)/(\rho(1 - \rho))\) and \(\sigma_X^2 = (1 - 2\rho + 2\rho^2)/(\rho^2 (1 - \rho)^2)\). The standardized \(z_j\) satisfies the unit-variance Layer 1 convention.

rho is the quantile parameter — rho = 0.5 is the symmetric Laplace, rho < 0.5 skews left, rho > 0.5 skews right. The package refuses values outside (0.05, 0.95) because the moment standardization becomes numerically unstable near the degenerate boundaries.

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

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

References

Yu, K., & Zhang, J. (2005). A three-parameter asymmetric Laplace distribution and its extension. Communications in Statistics — Theory and Methods, 34(9-10), 1867–1879. doi:10.1080/03610920500199018 .

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_skewn for an alternative asymmetric shape with smoother (Gaussian-like) tails; ralaplace for the underlying generator; the M2 G-distribution catalog vignette.

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

Examples

if (requireNamespace("LaplacesDemon", quietly = TRUE)) {
  # Left-skewed (rho < 0.5).
  gen_effects_ald(J = 10L, rho = 0.3)

  # Symmetric Laplace (rho = 0.5) — sharp peak at zero with exponential tails.
  gen_effects_ald(J = 50L, rho = 0.5, sigma_tau = 0.15)
}
#> # A tibble: 50 × 3
#>    site_index     z_j    tau_j
#>         <int>   <dbl>    <dbl>
#>  1          1  0.295   0.0443 
#>  2          2  1.81    0.271  
#>  3          3 -0.0665 -0.00997
#>  4          4 -0.807  -0.121  
#>  5          5 -0.320  -0.0481 
#>  6          6 -0.540  -0.0810 
#>  7          7 -0.261  -0.0391 
#>  8          8  0.0419  0.00628
#>  9          9 -1.03   -0.154  
#> 10         10  0.214   0.0322 
#> # ℹ 40 more rows