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. If y2 is omitted and y1 has length \(\ge 2\), covary() delegates to covary_clique() to declare all pairwise covariance edges.
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 (or list of them if y1 is a vector).

Details

Passing a character vector of responses (or calling covary_clique()) declares all pairwise covariance edges among them, forming a complete covariance sub-graph (clique).

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.

Shipley B, Douma JC (2021). “Testing Piecewise Structural Equations Models in the Presence of Latent Variables and Including Correlated Errors.” Structural Equation Modeling: A Multidisciplinary Journal, 28(4), 582–589. doi:10.1080/10705511.2020.1871355 .

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]
# Declare all pairwise covariance edges in a 3-response clique:
covary(c("activity", "boldness", "exploration"))
#> [[1]]
#> <covariance edge> rho12(activity, boldness) [residual]
#> 
#> [[2]]
#> <covariance edge> rho12(activity, exploration) [residual]
#> 
#> [[3]]
#> <covariance edge> rho12(boldness, exploration) [residual]
#>