Define a hierarchical nesting structure

Specifies a hierarchical (nesting) level in the model where group-level units are nested within higher-level entities. Unlike multiple-membership structures, each group belongs to exactly one nesting-level unit. Can model either random effects or fixed effects at the nesting level.

Usage

hm(id, vars = NULL, name = NULL, type = "RE", showFE = FALSE, ar = FALSE)

Arguments

id: An id object specifying the nesting-level identifier: id(hmid) where hmid identifies the higher-level units (e.g., countries, regions).
vars: A vars object specifying nesting-level covariates, or NULL for intercept-only effects. Supports interactions (*, :) and transformations (I()).
name: Unquoted variable name for nesting-level labels (optional). If provided, these labels will be displayed in model output for fixed effects.
type: Character; either "RE" for random effects (default) or "FE" for fixed effects at the nesting level.
showFE: Logical; if TRUE and type = "FE", fixed effect estimates for each nesting-level unit are included in output. Default: FALSE.
ar: Logical; if TRUE, random effects evolve autoregressively across participations at the nesting level. Requires sequential participation indicators in the data. Default: FALSE.

Value

A bml_hm object containing the hierarchical specification.

Details

Hierarchical vs. Multiple-Membership:

Hierarchical structures (hm) model strict nesting: each group belongs to exactly one higher-level unit. Use mm when groups can have memberships in multiple units.

Random vs. Fixed Effects:

Random effects (type = "RE"): Nesting-level units are treated as a random sample from a population. Best when you have many units and want to generalize.
Fixed effects (type = "FE"): Each unit gets its own parameter. Best when you have few units or want to estimate unit-specific effects.

Cross-Classification:

Multiple hm() blocks create cross-classified models where groups are simultaneously nested within multiple non-nested hierarchies (e.g., schools within both neighborhoods and districts).

References

Goldstein, H. (2011). Multilevel Statistical Models (4th ed.). Wiley.

Rabe-Hesketh, S., & Skrondal, A. (2012). Multilevel and Longitudinal Modeling Using Stata (3rd ed.). Stata Press.

Examples

if (FALSE) { # \dontrun{
# Random effects with covariates
hm(
  id = id(cid),
  vars = vars(gdp + democracy),
  name = cname,
  type = "RE"
)

# Random intercepts only
hm(
  id = id(cid),
  vars = NULL,
  type = "RE"
)

# Fixed effects
hm(
  id = id(cid),
  vars = NULL,
  name = cname,
  type = "FE",
  showFE = TRUE  # Show estimates for each country
)

# Autoregressive random effects
hm(
  id = id(cid),
  vars = NULL,
  type = "RE",
  ar = TRUE  # Effects evolve over time
)
} # }