cpsrm_run: Run the Co-Partner Social Relations Model

In roundRobinR: Manipulate and Analyze Round Robin Dyadic Data

Run the Co-Partner Social Relations Model

Description

Fits the Co-Partner Social Relations Model (CP-SRM) using restricted maximum likelihood (REML). The "block" method uses the Woodbury matrix identity for fast computation on large datasets; the "loop" method constructs the full covariance matrix by iterating over groups.

Usage

cpsrm_run(
  dv,
  actor_id,
  group_id,
  data,
  actor_dummies,
  partner_dummies,
  group_sizes = NULL,
  location_id = NULL,
  method = c("block", "loop"),
  zero_rho = FALSE,
  zero_actor = FALSE,
  zero_partner = FALSE,
  zero_group = FALSE,
  zero_location = FALSE,
  weight_partners = TRUE,
  fixed_effects = NULL,
  start = NULL,
  maxit = 200000L,
  stage1_maxit = 1000L,
  stage2_maxit = 1000L,
  tol = 1e-10,
  se_method = c("hessian", "none"),
  rho_boundary = 0.99,
  optimizer = c("Nelder-Mead", "L-BFGS-B"),
  verbose = FALSE,
  verbose_every = 50L
)

Arguments

dv	character; name of the dependent variable column
actor_id	character; name of the actor identifier column
group_id	character; name of the group identifier column
data	a data.frame containing all required variables
actor_dummies	character vector; actor dummy column names
partner_dummies	character vector; partner dummy column names
group_sizes	integer vector or NULL; per-row group sizes. Pass the group_sizes element from create_cp_dummies
location_id	character or NULL; optional higher-level clustering variable. Default NULL
method	character; "block" (default) or "loop"
zero_rho	logical; fix actor-partner correlation at zero. Default FALSE
zero_actor	logical; fix actor variance at zero. Default FALSE
zero_partner	logical; fix partner variance at zero. Default FALSE
zero_group	logical; fix group variance at zero. Default FALSE
zero_location	logical; fix location variance at zero. Default FALSE
weight_partners	logical; weight partner dummies by 1/(group\_size - 1). Default TRUE
fixed_effects	character vector or NULL; fixed effect predictor column names. Default NULL
start	named numeric vector or NULL; optional starting values
maxit	integer; maximum optimizer iterations. Default 200000
stage1_maxit	integer; stage 1 Nelder-Mead iterations. Default 1000
stage2_maxit	integer; stage 2 Nelder-Mead iterations. Default 1000
tol	numeric; convergence tolerance. Default 1e-10
se_method	character; "hessian" (default) or "none"
rho_boundary	numeric; boundary warning threshold. Default 0.99
optimizer	character; "Nelder-Mead" (default) or "L-BFGS-B"
verbose	logical; print progress. Default FALSE
verbose_every	integer; print every N evaluations. Default 50

Value

an object of class "cpsrm"

Reporting partner variance: RAW vs. COMBINED

Because each row sums multiple independent partner effects (its group_size - 1), \sigma_P^2 can be reported on two different, equally valid bases when weight_partners = FALSE:

• RAW (\sigma_P^2 itself): the variance of the partner-effect parameter, on the same per-person basis as \sigma_A^2. Use RAW whenever comparing the magnitude of partner effects to actor effects (e.g. tests of generalized reciprocity).

• COMBINED (partner's row multiplied by group_size - 1): partner identity's total contribution to the variance of a single observed score. Use COMBINED only when reading a full variance decomposition in which all components must sum to the outcome's total variance.

Mixing the two conventions in the same comparison is a common source of error: because COMBINED mechanically multiplies partner's numerator while RAW does not, a naive COMBINED-vs-RAW comparison can make partner effects look several times more (or less) important than actor effects even when the two are, per person, identical in magnitude. print.cpsrm/summary.cpsrm report both whenever weight_partners = FALSE and group size is constant across the data; when group size varies, or weight_partners = TRUE (partner dummies already rescaled to average rather than sum partner effects), only RAW is shown.

Testing variance components: use the boundary-corrected LRT

cpsrm_run reports a Wald z-statistic (estimate / SE) for each variance component, but variance components are bounded below by zero, so the usual two-sided reference distribution is not correct for testing whether a variance component is zero. The standard correction (Self & Liang, 1987; Snijders & Bosker, 2012; Stram & Lee, 1994) is to fit the model with and without the component of interest (e.g. zero_partner = TRUE vs. FALSE), form the likelihood-ratio statistic from each fit's fit["reml_loglik"] (LRT = -2(\ell_{restricted} - \ell_{full})), and compute a ONE-SIDED p-value:

p <- 0.5 * pchisq(LRT, df = 1, lower.tail = FALSE)

Testing TWO variance components jointly at their boundary (e.g. actor and partner both zero) is NOT a simple halving of the df = 2 chi-square, because both parameters are boundary-constrained; it requires the three-part mixture (Self & Liang, 1987):

p <- 0.25 * pchisq(LRT, df = 0, lower.tail = FALSE) +
     0.50 * pchisq(LRT, df = 1, lower.tail = FALSE) +
     0.25 * pchisq(LRT, df = 2, lower.tail = FALSE)

(the df = 0 term is always 0 for any LRT > 0). Applying the plain, uncorrected pchisq p-value, or halving the df = 2 joint test the same way as a single-component test, both misstate significance and are not valid inferential procedures for this model.

See Also

create_cp_dummies

Examples

# Prepare dummies using create_cp_dummies(), bind onto data, then call
# cpsrm_run(). See create_cp_dummies() documentation for a full example.

roundRobinR documentation built on Sept. 18, 2026, 1:06 a.m.