Add support for ADMGs (Acyclic Directed Mixed Graphs)

[Copilot]

This PR implements full support for ADMGs (Acyclic Directed Mixed Graphs) in caugi, addressing issue #[issue_number].

What is an ADMG?

An ADMG (Acyclic Directed Mixed Graph) is a causal graph structure that combines:

• Directed edges (-->) representing direct causal relationships
• Bidirected edges (<->) representing latent confounding (unmeasured common causes)

ADMGs must be acyclic with respect to directed edges, but bidirected edges can form cycles. This makes them ideal for representing causal systems with hidden confounders without explicitly modeling the latent variables.

Usage Example

library(caugi)

# Create an ADMG with directed and bidirected edges
admg <- caugi_graph(
  X %-->% Y,
  X %<->% Y,  # Latent confounding between X and Y
  Z %-->% X,
  Z %-->% Y,
  class = "ADMG"
)

# Query bidirected neighbors (representing confounded variables)
bidirected(admg, X)  # Returns: Y
bidirected(admg, Y)  # Returns: X

# All standard queries work
parents(admg, Y)     # Returns: X, Z
children(admg, Z)    # Returns: X, Y

Changes

Rust Backend

• New ADMG module (src/rust/src/graph/admg.rs): Implements ADMG structure with O(1) slice queries for parents, children, and bidirected neighbors
• GraphView updates: Added Admg variant and bidirected_of() method
• Validation: Added is_admg_type_ptr() to validate ADMG constraints (acyclic directed edges, no undirected/partial edges)
• Integration: Updated graphview_new() constructor and all match statements

R Interface

• Constructor: caugi_graph() now accepts class = "ADMG"
• Query function: New bidirected() function to retrieve bidirected neighbors
• Tests: Comprehensive test coverage for ADMG construction, validation, and queries
• Documentation: Updated README, vignette, and function documentation with ADMG examples

Implementation Details

The ADMG implementation follows the same pattern as existing DAG and PDAG classes:

• Packed neighborhoods with separate sections for parents, bidirected neighbors, and children
• Validates acyclicity using the existing directed_part_is_acyclic() algorithm
• Rejects undirected (---) and partial edges (o->, --o, o-o) at construction time
• Supports all standard graph queries: parents(), children(), neighbors(), ancestors(), descendants(), markov_blanket_of(), and exogenous_nodes()

Testing

All new functionality is tested:

• ✅ ADMG accepts directed and bidirected edges
• ✅ ADMG rejects undirected and partial edges
• ✅ ADMG validates acyclicity on directed edges
• ✅ ADMG allows bidirected cycles
• ✅ bidirected() query returns correct neighbors

Closes #[issue_number]

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Support ADMGs</issue_title>
<issue_description></issue_description>

Comments on the Issue (you are @copilot in this section)

Fixes #22

---

💬 Share your feedback on Copilot coding agent for the chance to win a $200 gift card! Click here to start the survey.

[codecov-commenter]

⚠️ Please install the to ensure uploads and comments are reliably processed by Codecov.

Codecov Report

❌ Patch coverage is 86.97183% with 37 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
src/rust/src/graph/view.rs	0.00%	17 Missing ⚠️
src/rust/src/lib.rs	0.00%	17 Missing ⚠️
src/rust/src/graph/admg.rs	98.80%	3 Missing ⚠️

📢 Thoughts on this report? Let us know!