Declare a covariance edge between two responses

A covariance edge is a double-headed arc, not a directed path: it states that two responses are allowed to remain associated after their modelled predictors, without asserting a direction or a mediated effect. With level = NULL it is a residual correlation (rho12, within-observation, eps_y1 <-> eps_y2); with a grouping level it is a higher-level random-effect correlation (corpair, between-unit, u_level,y1 <-> u_level,y2). These are biologically distinct and are reported separately by covariances(); neither enters paths() or the effect decomposition.

Usage

covary(y1, y2, level = NULL, structure = "unstructured")

Arguments

y1, y2: Response (node) names, as strings. Matched to nodes by name or response variable, exactly like a predictor token.
level: NULL for a residual (rho12) edge, or a grouping name (e.g. "id", "species") for a higher-level random-effect (corpair) edge.
structure: Label for the covariance structure (informational), e.g. "unstructured", "phylo".

Value

A drm_covary declaration object.

Details

Pass declarations to drm_sem() / drm_psem() via their covariances argument. A declared covariance edge makes basis_set() / dsep() drop the y1 _||_ y2 | predictors independence claim, because the model has explicitly allowed y1 and y2 to stay coupled.

References

Shipley B (2016). Cause and Correlation in Biology: A User's Guide to Path Analysis, Structural Equations and Causal Inference with R, 2nd edition. Cambridge University Press, Cambridge.

Bollen KA (1989). Structural Equations with Latent Variables. Wiley, New York.

Examples

# A residual (rho12) covariance edge between two responses:
covary("activity", "boldness")
#> <covariance edge> rho12(activity, boldness) [residual]
# A higher-level random-effect (corpair) edge sharing the `id` grouping:
covary("activity", "boldness", level = "id")
#> <covariance edge> corpair(id: activity, boldness) [higher-level]