Package 'hlmLab'

Contextual effect for a Level-1 predictor (Mundlak decomposition)

Description

Given a multilevel model with a within-cluster centered predictor and its cluster-mean counterpart (Mundlak specification), this function extracts the within- and between-cluster effects and computes the contextual effect (between - within).

Usage

hlm_context(model, x_within, x_between)

Arguments

model	A fitted lmerMod model.
x_within	Name of the within-cluster centered predictor (string).
x_between	Name of the cluster-mean predictor (string).

Value

An object of class hlm_context, which is a tibble with:

effect_type	Within, between, or contextual.
estimate	Estimate of the effect.
se	Standard error (approximate for contextual).

Examples

## Not run: 
m <- lme4::lmer(math_score ~ SES_c + SES_mean + (1 | school_id), data = d)
ctx <- hlm_context(m, x_within = "SES_c", x_between = "SES_mean")
ctx
hlm_context_plot(ctx)

## End(Not run)

---

Convenience wrapper to plot contextual effects

Description

Convenience wrapper to plot contextual effects

Usage

hlm_context_plot(object)

Arguments

object

An object of class hlm_context.

Value

A ggplot object.

---

Multilevel variance decomposition (within/between/longitudinal)

Description

Decomposes a continuous variable into between-cluster, and within-cluster components (2-level), or into between-cluster (B), between-person (P), and within-person (W) components for longitudinal 3-level data.

Usage

hlm_decompose(data, var, cluster, id = NULL, time = NULL)

Arguments

data	A data frame.
var	Name of the focal variable (string).
cluster	Name of the cluster ID variable (e.g., school/classroom).
id	Optional person ID variable for longitudinal data.
time	Optional time variable (not required for the algebra, but noted in the output for clarity).

Details

This is primarily a teaching tool: it shows how total variance is partitioned across levels.

Value

An object of class hlm_decompose with components:

data	Original data with added decomposition columns.
summary	A tibble summarizing variance components and shares.

Examples

## Not run: 
hlm_decompose(d, var = "math_score", cluster = "school_id")
hlm_decompose(d, var = "math_score", cluster = "school_id",
              id = "student_id", time = "wave")

## End(Not run)

---

Longitudinal three-level variance decomposition (B-P-W)

Description

Convenience wrapper around hlm_decompose() for 3-level data: clusters (e.g., schools), persons within clusters, and repeated measures within persons over time.

Usage

hlm_decompose_long(data, var, cluster, id, time = NULL)

Arguments

data	A data frame.
var	Name of the focal variable (string).
cluster	Cluster ID (e.g., school/classroom) (string).
id	Person ID within cluster (string).
time	Optional time variable (string); stored in the output for reference but not required for the algebra.

Value

An object of class hlm_decompose with between-cluster (B), between-person (P), and within-person (W) variance components and shares.

Examples

## Not run: 
hlm_decompose_long(data = d_long,
                   var = "math_score",
                   cluster = "school_id",
                   id = "student_id",
                   time = "wave")

## End(Not run)

---

Intraclass correlation and design effect from a random-intercept model

Description

Computes the intraclass correlation (ICC) and, optionally, a design effect from a random-intercept multilevel model fitted with lme4::lmer().

Usage

hlm_icc(model, cluster_size = NULL)

Arguments

model	A fitted lmerMod object with at least one random intercept.
cluster_size	Optional scalar giving the average cluster size, used to compute the design effect. If NULL, the design effect is not computed.

Value

An object of class hlm_icc with components:

icc	Estimated intraclass correlation.
deff	Design effect (if cluster_size supplied).
re_var	Random intercept variance.
resid_var	Residual variance.

Examples

## Not run: 
library(lme4)
m <- lmer(math_score ~ SES + (1 | school_id), data = d)
hlm_icc(m, cluster_size = 25)

## End(Not run)

---

Teaching plot for intraclass correlation (ICC)

Description

Visualizes the intraclass correlation by plotting the between- and within-cluster variance components as a stacked bar. This is intended as a teaching diagram to help students see how the ICC reflects the share of variance that lies between clusters.

Usage

hlm_icc_plot(model, cluster_size = NULL)

Arguments

model	A fitted lmerMod model with a random intercept.
cluster_size	Optional scalar giving the average cluster size, passed to hlm_icc() to compute the design effect.

Value

A ggplot object.

---

Geometry of a cross-level interaction (random slopes fan plot)

Description

Produces a "fan plot" of predicted lines for each cluster to illustrate a cross-level interaction (random slope) in a multilevel model.

Usage

hlm_xint_geom(model, x_within, cluster, n_points = 20, n_clusters = 20)

Arguments

model	A fitted lmerMod model with a random slope term of the form (x_within | cluster).
x_within	Name of the Level-1 predictor with a random slope (string).
cluster	Name of the clustering factor (string).
n_points	Number of points to plot along the x-axis. Defaults to 20.
n_clusters	Maximum number of clusters to display (sampled) for clarity.

Value

A ggplot object showing predicted lines by cluster.

Examples

## Not run: 
m <- lme4::lmer(math_score ~ SES_c + SES_mean + (SES_c | school_id), data = d)
hlm_xint_geom(m, x_within = "SES_c", cluster = "school_id")

## End(Not run)

---

Plot method for hlm_context objects

Description

Produces an error-bar plot of within, between, and contextual effects with 95% confidence intervals. Intended as a teaching diagram.

Usage

## S3 method for class 'hlm_context'
plot(x, ...)

Arguments

x	An object of class hlm_context.
...	Not used.

Value

A ggplot object.

---

Plot method for hlm_decompose objects

Description

Produces a simple bar chart of variance shares across components, suitable for teaching how variance is partitioned across levels.

Usage

## S3 method for class 'hlm_decompose'
plot(x, ...)

Arguments

x	An object of class hlm_decompose.
...	Not used.

Value

A ggplot object.

---