Package 'caugi'

Description

Arrange two plots side-by-side with configurable spacing. The + and | operators are equivalent and can be used interchangeably. Compositions can be nested to create complex multi-plot layouts.

Arguments

Details

The spacing between plots is controlled by the global option caugi_options()$plot$spacing, which defaults to grid::unit(1, "lines"). Compositions can be nested arbitrarily:

• p1 + p2 - two plots side-by-side

• (p1 + p2) + p3 - three plots in a row

• (p1 + p2) / p3 - two plots on top, one below

Value

A caugi_plot object containing the composed layout

See Also

caugi_options() for configuring spacing and default styles

Other plotting: caugi_layout(), caugi_layout_bipartite(), caugi_layout_circle(), caugi_layout_fruchterman_reingold(), caugi_layout_kamada_kawai(), caugi_layout_sugiyama(), caugi_layout_tiered(), caugi_plot(), divide-caugi_plot-caugi_plot, plot()

Examples

cg1 <- caugi(A %-->% B, B %-->% C)
cg2 <- caugi(X %-->% Y, Y %-->% Z)

p1 <- plot(cg1, main = "Graph 1")
p2 <- plot(cg2, main = "Graph 2")

# Horizontal composition
p1 + p2
p1 | p2 # equivalent

# Adjust spacing
caugi_options(plot = list(spacing = grid::unit(2, "lines")))
p1 + p2

Description

Computes an adjustment set for X -> Y in a DAG.

Usage

adjustment_set(
  cg,
  X = NULL,
  Y = NULL,
  X_index = NULL,
  Y_index = NULL,
  type = c("optimal", "parents", "backdoor")
)

Arguments

Details

Types supported:

• "parents": $\bigcup \mathrm{Pa}(X)$ minus $X \cup Y$

• "backdoor": Pearl backdoor formula

• "optimal": O-set (only for single x and single y)

Value

A character vector of node names representing the adjustment set.

See Also

Other adjustment: all_adjustment_sets_admg(), all_backdoor_sets(), d_separated(), is_valid_adjustment_admg(), is_valid_backdoor(), minimal_separator()

Examples

cg <- caugi(
  C %-->% X,
  X %-->% F,
  X %-->% D,
  A %-->% X,
  A %-->% K,
  K %-->% Y,
  D %-->% Y,
  D %-->% G,
  Y %-->% H,
  class = "DAG"
)

adjustment_set(cg, "X", "Y", type = "parents") # C, A
adjustment_set(cg, "X", "Y", type = "backdoor") # C, A
adjustment_set(cg, "X", "Y", type = "optimal") # K

Description

Compute the Adjustment Identification Distance (AID) between two graphs using the gadjid Rust package.

Usage

aid(truth, guess, type = c("oset", "ancestor", "parent"), normalized = TRUE)

Arguments

Value

A numeric representing the AID between the two graphs, if normalized = TRUE, or an integer count if normalized = FALSE.

See Also

Other metrics: hd(), shd()

Examples

set.seed(1)
truth <- generate_graph(n = 100, m = 200, class = "DAG")
guess <- generate_graph(n = 100, m = 200, class = "DAG")
aid(truth, guess) # 0.0187

Description

Enumerates all valid adjustment sets for estimating the causal effect of X on Y in an ADMG, up to a specified maximum size.

Usage

all_adjustment_sets_admg(
  cg,
  X = NULL,
  Y = NULL,
  X_index = NULL,
  Y_index = NULL,
  minimal = TRUE,
  max_size = 3L
)

Arguments

Value

A list of character vectors, each a valid adjustment set (possibly empty list if none exist).

See Also

Other adjustment: adjustment_set(), all_backdoor_sets(), d_separated(), is_valid_adjustment_admg(), is_valid_backdoor(), minimal_separator()

Examples

cg <- caugi(
  L %-->% X,
  X %-->% Y,
  L %-->% Y,
  M %-->% Y,
  class = "ADMG"
)

all_adjustment_sets_admg(cg, X = "X", Y = "Y", minimal = TRUE)
# Returns {L} as minimal adjustment set

Description

This function returns the backdoor sets up to size max_size, which per default is set to 10.

Usage

all_backdoor_sets(
  cg,
  X = NULL,
  Y = NULL,
  X_index = NULL,
  Y_index = NULL,
  minimal = TRUE,
  max_size = 3L
)

Arguments

Value

A list of character vectors, each an adjustment set (possibly empty).

See Also

Other adjustment: adjustment_set(), all_adjustment_sets_admg(), d_separated(), is_valid_adjustment_admg(), is_valid_backdoor(), minimal_separator()

Examples

cg <- caugi(
  C %-->% X,
  X %-->% F,
  X %-->% D,
  A %-->% X,
  A %-->% K,
  K %-->% Y,
  D %-->% Y,
  D %-->% G,
  Y %-->% H,
  class = "DAG"
)

all_backdoor_sets(cg, X = "X", Y = "Y", max_size = 3L, minimal = FALSE)
#> [[1]]
#> [1] "A"
#>
#> [[2]]
#> [1] "K"
#>
#> [[3]]
#> [1] "C" "A"
#>
#> [[4]]
#> [1] "C" "K"
#>
#> [[5]]
#> [1] "A" "K"
#>
#> [[6]]
#> [1] "C" "A" "K"

all_backdoor_sets(cg, X = "X", Y = "Y", max_size = 3L, minimal = TRUE)
#> [[1]]
#> [1] "A"
#>
#> [[2]]
#> [1] "K"

Description

Get ancestors of nodes in a caugi

Usage

ancestors(
  cg,
  nodes = NULL,
  index = NULL,
  open = caugi_options("use_open_graph_definition")
)

Arguments

Value

Either a character vector of node names (if a single node is requested) or a list of character vectors (if multiple nodes are requested).

See Also

Other queries: anteriors(), children(), descendants(), districts(), edge_types(), edges(), exogenous(), is_acyclic(), is_admg(), is_ag(), is_caugi(), is_cpdag(), is_dag(), is_empty_caugi(), is_mag(), is_mpdag(), is_pdag(), is_simple(), is_ug(), m_separated(), markov_blanket(), neighbors(), nodes(), parents(), posteriors(), same_nodes(), spouses(), subgraph(), topological_sort()

Examples

cg <- caugi(
  A %-->% B,
  B %-->% C,
  class = "DAG"
)
ancestors(cg, "A") # NULL
ancestors(cg, "A", open = FALSE) # A
ancestors(cg, index = 2) # "A"
ancestors(cg, "B") # "A"
ancestors(cg, c("B", "C"))
#> $B
#> [1] "A"
#>
#> $C
#> [1] "A" "B"

Description

Get the anterior set of nodes in a graph. The anterior set (Richardson and Spirtes, 2002) includes all nodes reachable by following paths where every edge is either undirected or directed toward the target node.

For DAGs, the anterior set equals the ancestor set (since there are no undirected edges). For PDAGs, it includes both ancestors and nodes reachable via undirected edges.

Usage

anteriors(
  cg,
  nodes = NULL,
  index = NULL,
  open = caugi_options("use_open_graph_definition")
)

Arguments

Value

Either a character vector of node names (if a single node is requested) or a list of character vectors (if multiple nodes are requested).

References

Richardson, T. and Spirtes, P. (2002). Ancestral graph Markov models. The Annals of Statistics, 30(4):962-1030.

See Also

Other queries: ancestors(), children(), descendants(), districts(), edge_types(), edges(), exogenous(), is_acyclic(), is_admg(), is_ag(), is_caugi(), is_cpdag(), is_dag(), is_empty_caugi(), is_mag(), is_mpdag(), is_pdag(), is_simple(), is_ug(), m_separated(), markov_blanket(), neighbors(), nodes(), parents(), posteriors(), same_nodes(), spouses(), subgraph(), topological_sort()

Examples

# PDAG example with directed and undirected edges
cg <- caugi(
  A %-->% B %---% C,
  B %-->% D,
  class = "PDAG"
)
anteriors(cg, "A") # NULL (no anteriors)
anteriors(cg, "A", open = FALSE) # A
anteriors(cg, "C") # A, B
anteriors(cg, "D") # A, B, C

# For DAGs, anteriors equals ancestors
cg_dag <- caugi(
  A %-->% B %-->% C,
  class = "DAG"
)
anteriors(cg_dag, "C") # A, B

Description

Does not take other edge types than the one found in a PDAG.

Usage

as_adjacency(x)

Arguments

Value

An integer 0/1 adjacency matrix with row/col names.

See Also

Other conversions: as_bnlearn(), as_caugi(), as_dagitty(), as_igraph()

Examples

cg <- caugi(
  A %-->% B,
  class = "DAG"
)
adj <- as_adjacency(cg)

Description

Convert a caugi to a bnlearn network

Usage

as_bnlearn(x)

Arguments

Value

A bnlearn DAG.

See Also

Other conversions: as_adjacency(), as_caugi(), as_dagitty(), as_igraph()

Examples

cg <- caugi(
  A %-->% B,
  class = "DAG"
)
g_bn <- as_bnlearn(cg)

Description

Convert an object to a caugi. The object can be a graphNEL, matrix, tidygraph, daggity, bn, or igraph.

Usage

as_caugi(
  x,
  class = c("DAG", "UG", "PDAG", "MPDAG", "ADMG", "AG", "PAG", "UNKNOWN"),
  simple = TRUE,
  collapse = FALSE,
  collapse_to = "---",
  ...
)

Arguments

Details

For matrices, as_caugi assumes that the rows are the from nodes and the columns are the to nodes. Thus, for a graph, G: A –> B, we would have that G["A", "B"] == 1 and G["B", "A"] == 0. For PAGs, the integer codes are as follows (as used in pcalg):

• 0: no edge

• 1: circle (e.g., ⁠A o-o B⁠ or ⁠A --o B⁠)

• 2: arrowhead (e.g., ⁠A --> B⁠ or ⁠A o-> B⁠)

• 3: tail (e.g., ⁠A --o B⁠ or A --- B)

Value

A caugi object.

See Also

Other conversions: as_adjacency(), as_bnlearn(), as_dagitty(), as_igraph()

Examples

# igraph
ig <- igraph::graph_from_literal(A - +B, B - +C)
cg_ig <- as_caugi(ig, class = "DAG")

# graphNEL
gn <- graph::graphNEL(nodes = c("A", "B", "C"), edgemode = "directed")
gn <- graph::addEdge("A", "B", gn)
gn <- graph::addEdge("B", "C", gn)
cg_gn <- as_caugi(gn, class = "DAG")

# adjacency matrix
m <- matrix(0L, 3, 3, dimnames = list(LETTERS[1:3], LETTERS[1:3]))
m["A", "B"] <- 1L
m["B", "C"] <- 1L
cg_adj <- as_caugi(m, class = "DAG")

# bnlearn
bn <- bnlearn::model2network("[A][B|A][C|B]")
cg_bn <- as_caugi(bn, class = "DAG")

# dagitty
dg <- dagitty::dagitty("dag {
 A -> B
 B -> C
 }")
cg_dg <- as_caugi(dg, class = "DAG")

cg <- caugi(A %-->% B %-->% C, class = "DAG")

# check that all nodes are equal in all graph objects
for (cg_converted in list(cg_ig, cg_gn, cg_adj, cg_bn, cg_dg)) {
  stopifnot(identical(nodes(cg), nodes(cg_converted)))
  stopifnot(identical(edges(cg), edges(cg_converted)))
}

# collapse mutual edges
ig2 <- igraph::graph_from_literal(A - +B, B - +A, C - +D)
cg2 <- as_caugi(ig2, class = "PDAG", collapse = TRUE, collapse_to = "---")

# coded integer matrix for PAGs (pcalg style)
nm <- c("A", "B", "C", "D")
M <- matrix(0L, 4, 4, dimnames = list(nm, nm))

# A --> B
M["A", "B"] <- 2L # mark at B end
M["B", "A"] <- 3L # mark at A end

# A --- C
M["A", "C"] <- 3L
M["C", "A"] <- 3L

# B o-> C
M["B", "C"] <- 2L
M["C", "B"] <- 1L

# C o-o D
M["C", "D"] <- 1L
M["D", "C"] <- 1L

cg <- as_caugi(M, class = "PAG")

Description

Convert a caugi to a dagitty graph

Usage

as_dagitty(x)

Arguments

Value

A dagitty object.

See Also

Other conversions: as_adjacency(), as_bnlearn(), as_caugi(), as_igraph()

Examples

cg <- caugi(
  A %-->% B,
  class = "DAG"
)
g_dg <- as_dagitty(cg)

Description

Convert a caugi to an igraph object

Usage

as_igraph(x, ...)

Arguments

Value

An igraph object representing the same graph structure.

See Also

Other conversions: as_adjacency(), as_bnlearn(), as_caugi(), as_dagitty()

Examples

cg <- caugi(
  A %-->% B,
  class = "DAG"
)
ig <- as_igraph(cg)

Description

Forces lazy compilation of the caugi graph without running a specific query. Useful to pre-initialize the graph.

Usage

build(cg)

Arguments

Value

The input caugi object (invisibly), with its graph built.

See Also

Other verbs: caugi_verbs

Examples

cg <- caugi(A %-->% B, class = "DAG")
build(cg) # initialize graph without querying

Description

Create a caugi from a series of edge expressions using infix operators. Nodes can be specified as symbols, strings, or numbers.

The following edge operators are supported by default:

• ⁠%-->%⁠ for directed edges (A –> B)

• ⁠%---%⁠ for undirected edges (A — B)

• ⁠%<->%⁠ for bidirected edges (A <-> B)

• ⁠%o->%⁠ for partially directed edges (A o-> B)

• ⁠%--o%⁠ for partially undirected edges (A –o B)

• ⁠%o-o%⁠ for partial edges (A o-o B)

You can register additional edge types using register_caugi_edge().

Usage

caugi(
  ...,
  from = NULL,
  edge = NULL,
  to = NULL,
  nodes = NULL,
  edges_df = NULL,
  simple = TRUE,
  build = NULL,
  class = c("AUTO", "DAG", "UG", "PDAG", "MPDAG", "ADMG", "AG", "UNKNOWN"),
  state = NULL,
  .session = NULL
)

Arguments

Value

A caugi S7 object containing the nodes, edges, and a pointer to the underlying Rust graph structure.

Examples

# create a simple DAG (using NSE)
cg <- caugi(
  A %-->% B + C,
  B %-->% D,
  class = "DAG"
)

# create a PDAG with undirected edges (using NSE)
cg2 <- caugi(
  A %-->% B + C,
  B %---% D,
  E, # no neighbors for this node
  class = "PDAG"
)

# create a DAG (using SE)
cg3 <- caugi(
  from = c("A", "A", "B"),
  edge = c("-->", "-->", "-->"),
  to = c("B", "C", "D"),
  nodes = c("A", "B", "C", "D", "E"),
  class = "DAG"
)

# create a non-simple graph
cg4 <- caugi(
  A %-->% B,
  B %-->% A,
  class = "UNKNOWN",
  simple = FALSE
)

cg4@simple # FALSE
cg4@graph_class # "UNKNOWN"

Description

Returns the default options for the caugi package. Useful for resetting options to their original state.

Usage

caugi_default_options()

Value

A list of default options for caugi.

See Also

caugi_options() for setting and getting options

Examples

# Get defaults
caugi_default_options()

# Reset to defaults
caugi_options(caugi_default_options())

Description

Converts a JSON string in the native caugi format back to a caugi graph. This is a lower-level function; consider using read_caugi() for reading from files.

Usage

caugi_deserialize(json, lazy)

Arguments

Value

A caugi object.

See Also

Other export: caugi_dot(), caugi_export(), caugi_graphml(), caugi_mermaid(), caugi_serialize(), export-classes, format-caugi, format-dot, format-graphml, format-mermaid, knit_print.caugi_export, read_caugi(), read_graphml(), to_dot(), to_graphml(), to_mermaid(), write_caugi(), write_dot(), write_graphml(), write_mermaid()

Examples

cg <- caugi(A %-->% B, class = "DAG")
json <- caugi_serialize(cg)
cg2 <- caugi_deserialize(json)

Description

An S7 object that wraps a DOT format string for displaying caugi graphs. When printed interactively, displays the DOT string cleanly.

Usage

caugi_dot(content)

Arguments

See Also

Other export: caugi_deserialize(), caugi_export(), caugi_graphml(), caugi_mermaid(), caugi_serialize(), export-classes, format-caugi, format-dot, format-graphml, format-mermaid, knit_print.caugi_export, read_caugi(), read_graphml(), to_dot(), to_graphml(), to_mermaid(), write_caugi(), write_dot(), write_graphml(), write_mermaid()

Description

A base class for all caugi export formats. Provides common structure and behavior for different export formats (DOT, GraphML, etc.).

Usage

caugi_export(content = character(0), format = character(0))

Arguments

See Also

Other export: caugi_deserialize(), caugi_dot(), caugi_graphml(), caugi_mermaid(), caugi_serialize(), export-classes, format-caugi, format-dot, format-graphml, format-mermaid, knit_print.caugi_export, read_caugi(), read_graphml(), to_dot(), to_graphml(), to_mermaid(), write_caugi(), write_dot(), write_graphml(), write_mermaid()

Description

An S7 object that wraps a GraphML format string for caugi graphs.

Usage

caugi_graphml(content)

Arguments

See Also

Other export: caugi_deserialize(), caugi_dot(), caugi_export(), caugi_mermaid(), caugi_serialize(), export-classes, format-caugi, format-dot, format-graphml, format-mermaid, knit_print.caugi_export, read_caugi(), read_graphml(), to_dot(), to_graphml(), to_mermaid(), write_caugi(), write_dot(), write_graphml(), write_mermaid()

Description

Computes node coordinates for graph visualization using specified layout algorithm. If the graph has not been built yet, it will be built automatically before computing the layout.

Usage

caugi_layout(
  x,
  method = c("auto", "sugiyama", "fruchterman-reingold", "kamada-kawai", "bipartite",
    "tiered", "circle"),
  packing_ratio = 1.618034,
  ...
)

Arguments

Value

A data.frame with columns name, x, and y containing node names and their coordinates.

Layout Algorithms

Sugiyama (Hierarchical Layout)

Optimized for directed acyclic graphs (DAGs). Places nodes in layers to emphasize hierarchical structure and causal flow from top to bottom. Edges are routed to minimize crossings. Best for visualizing clear cause-effect relationships. Only works with directed edges.

Fruchterman-Reingold (Spring-Electrical)

Fast force-directed layout using a spring-electrical model. Treats edges as springs and nodes as electrically charged particles. Produces organic, symmetric layouts with uniform edge lengths. Good for general-purpose visualization and works with all edge types. Results are deterministic.

Kamada-Kawai (Stress Minimization)

High-quality force-directed layout that minimizes "stress" by making Euclidean distances proportional to graph-theoretic distances. Better preserves the global structure and path lengths compared to Fruchterman-Reingold. Ideal for publication-quality visualizations where accurate distance representation matters. Works with all edge types and produces deterministic results.

Circle

Places nodes evenly along the perimeter of a circle. The first node is at the top and subsequent nodes proceed counter-clockwise. Useful for small graphs, cycle visualization, and as a deterministic fallback. Works with all edge types and ignores edge structure.

Source

Fruchterman, T. M. J., & Reingold, E. M. (1991). Graph drawing by force-directed placement. Software: Practice and Experience, 21(11), 1129-1164. doi:10.1002/spe.4380211102

Kamada, T., & Kawai, S. (1989). An algorithm for drawing general undirected graphs. Information Processing Letters, 31(1), 7-15. doi:10.1016/0020-0190(89)90102-6

Sugiyama, K., Tagawa, S., & Toda, M. (1981). Methods for visual understanding of hierarchical system structures. IEEE Transactions on Systems, Man, and Cybernetics, 11(2), 109-125. doi:10.1109/TSMC.1981.4308636

See Also

Other plotting: add-caugi_plot-caugi_plot, caugi_layout_bipartite(), caugi_layout_circle(), caugi_layout_fruchterman_reingold(), caugi_layout_kamada_kawai(), caugi_layout_sugiyama(), caugi_layout_tiered(), caugi_plot(), divide-caugi_plot-caugi_plot, plot()

Examples

cg <- caugi(
  A %-->% B + C,
  B %-->% D,
  C %-->% D,
  class = "DAG"
)

# Default: auto-selects best layout
layout <- caugi_layout(cg)

# Auto-selects tiered when tiers provided
cg_tiered <- caugi(X1 %-->% M1, X2 %-->% M2, M1 %-->% Y, M2 %-->% Y)
tiers <- list(c("X1", "X2"), c("M1", "M2"), "Y")
layout_auto <- caugi_layout(cg_tiered, tiers = tiers) # Uses "tiered"

# Explicitly use hierarchical layout
layout_sug <- caugi_layout(cg, method = "sugiyama")

# Use force-directed for organic appearance
layout_fr <- caugi_layout(cg, method = "fruchterman-reingold")

# Use stress minimization for publication quality
layout_kk <- caugi_layout(cg, method = "kamada-kawai")

# Place nodes on a circle
layout_circle <- caugi_layout(cg, method = "circle")

# Bipartite layout with auto-detected partition
cg_bp <- caugi(A %-->% X, A %-->% Y, B %-->% X, B %-->% Y)
layout_bp_rows <- caugi_layout(
  cg_bp,
  method = "bipartite",
  orientation = "rows"
)

# Explicit partition
partition <- c(TRUE, TRUE, FALSE, FALSE)
layout_bp_cols <- caugi_layout(
  cg_bp,
  method = "bipartite",
  partition = partition,
  orientation = "columns"
)

# Tiered layout with three tiers
cg_tiered <- caugi(
  X1 %-->% M1 + M2,
  X2 %-->% M1 + M2,
  M1 %-->% Y,
  M2 %-->% Y
)
tiers <- list(c("X1", "X2"), c("M1", "M2"), "Y")
layout_tiered <- caugi_layout(
  cg_tiered,
  method = "tiered",
  tiers = tiers,
  orientation = "rows"
)

Description

Computes node coordinates for bipartite graphs, placing nodes in two parallel lines (rows or columns) based on a partition. If the graph has not been built yet, it will be built automatically before computing the layout.

Usage

caugi_layout_bipartite(x, partition = NULL, orientation = c("columns", "rows"))

Arguments

Value

A data.frame with columns name, x, and y containing node names and their coordinates.

See Also

Other plotting: add-caugi_plot-caugi_plot, caugi_layout(), caugi_layout_circle(), caugi_layout_fruchterman_reingold(), caugi_layout_kamada_kawai(), caugi_layout_sugiyama(), caugi_layout_tiered(), caugi_plot(), divide-caugi_plot-caugi_plot, plot()

Examples

# Create a bipartite graph (causes -> effects)
cg <- caugi(A %-->% X, A %-->% Y, B %-->% X, B %-->% Y)
partition <- c(TRUE, TRUE, FALSE, FALSE) # A, B = causes, X, Y = effects

# Two horizontal rows (causes on top)
layout_rows <- caugi_layout_bipartite(cg, partition, orientation = "rows")

# Two vertical columns (causes on right)
layout_cols <- caugi_layout_bipartite(cg, partition, orientation = "columns")

Description

Computes node coordinates by placing nodes evenly along the perimeter of a circle. The first node is placed at the top of the circle, and subsequent nodes proceed counter-clockwise. Edge structure is ignored. Works with all edge types and produces deterministic results.

Usage

caugi_layout_circle(x, ...)

Arguments

Value

A data.frame with columns name, x, and y containing node names and their coordinates.

See Also

Other plotting: add-caugi_plot-caugi_plot, caugi_layout(), caugi_layout_bipartite(), caugi_layout_fruchterman_reingold(), caugi_layout_kamada_kawai(), caugi_layout_sugiyama(), caugi_layout_tiered(), caugi_plot(), divide-caugi_plot-caugi_plot, plot()

Examples

cg <- caugi(
  A %-->% B,
  B %-->% C,
  C %-->% D,
  D %-->% A
)
layout <- caugi_layout_circle(cg)

Description

Computes node coordinates using the Fruchterman-Reingold force-directed layout algorithm. Fast spring-electrical model that treats edges as springs and nodes as electrically charged particles. Produces organic, symmetric layouts with uniform edge lengths. Works with all edge types and produces deterministic results.

Usage

caugi_layout_fruchterman_reingold(x, packing_ratio = 1.618034, ...)

Arguments

Value

A data.frame with columns name, x, and y containing node names and their coordinates.

Source

Fruchterman, T. M. J., & Reingold, E. M. (1991). Graph drawing by force-directed placement. Software: Practice and Experience, 21(11), 1129-1164. doi:10.1002/spe.4380211102

See Also

Other plotting: add-caugi_plot-caugi_plot, caugi_layout(), caugi_layout_bipartite(), caugi_layout_circle(), caugi_layout_kamada_kawai(), caugi_layout_sugiyama(), caugi_layout_tiered(), caugi_plot(), divide-caugi_plot-caugi_plot, plot()

Examples

cg <- caugi(
  A %-->% B,
  B %<->% C,
  C %-->% D
)
layout <- caugi_layout_fruchterman_reingold(cg)

Description

Computes node coordinates using the Kamada-Kawai stress minimization algorithm. High-quality force-directed layout that minimizes "stress" by making Euclidean distances proportional to graph-theoretic distances. Better preserves global structure and path lengths compared to Fruchterman-Reingold. Ideal for publication-quality visualizations. Works with all edge types and produces deterministic results.

Usage

caugi_layout_kamada_kawai(x, packing_ratio = 1.618034, ...)

Arguments

Value

A data.frame with columns name, x, and y containing node names and their coordinates.

Source

Kamada, T., & Kawai, S. (1989). An algorithm for drawing general undirected graphs. Information Processing Letters, 31(1), 7-15. doi:10.1016/0020-0190(89)90102-6

See Also

Other plotting: add-caugi_plot-caugi_plot, caugi_layout(), caugi_layout_bipartite(), caugi_layout_circle(), caugi_layout_fruchterman_reingold(), caugi_layout_sugiyama(), caugi_layout_tiered(), caugi_plot(), divide-caugi_plot-caugi_plot, plot()

Examples

cg <- caugi(
  A %-->% B,
  B %<->% C,
  C %-->% D
)
layout <- caugi_layout_kamada_kawai(cg)

Description

Computes node coordinates using the Sugiyama hierarchical layout algorithm. Optimized for directed acyclic graphs (DAGs), placing nodes in layers to emphasize hierarchical structure and causal flow from top to bottom.

Usage

caugi_layout_sugiyama(x, packing_ratio = 1.618034, ...)

Arguments

Value

A data.frame with columns name, x, and y containing node names and their coordinates.

Source

Sugiyama, K., Tagawa, S., & Toda, M. (1981). Methods for visual understanding of hierarchical system structures. IEEE Transactions on Systems, Man, and Cybernetics, 11(2), 109-125. doi:10.1109/TSMC.1981.4308636

See Also

Other plotting: add-caugi_plot-caugi_plot, caugi_layout(), caugi_layout_bipartite(), caugi_layout_circle(), caugi_layout_fruchterman_reingold(), caugi_layout_kamada_kawai(), caugi_layout_tiered(), caugi_plot(), divide-caugi_plot-caugi_plot, plot()

Examples

cg <- caugi(A %-->% B + C, B %-->% D, C %-->% D, class = "DAG")
layout <- caugi_layout_sugiyama(cg)

Description

Computes node coordinates for graphs with multiple tiers (layers), placing nodes in parallel rows or columns based on tier assignments. If the graph has not been built yet, it will be built automatically before computing the layout.

Usage

caugi_layout_tiered(x, tiers, orientation = c("columns", "rows"))

Arguments

Value

A data.frame with columns name, x, y, and tier containing node names, their coordinates, and tier assignments (0-indexed). The returned data.frame also has an orientation attribute storing the orientation used. When passed to plot(), tier information is automatically extracted, so you don't need to specify tiers again.

See Also

Other plotting: add-caugi_plot-caugi_plot, caugi_layout(), caugi_layout_bipartite(), caugi_layout_circle(), caugi_layout_fruchterman_reingold(), caugi_layout_kamada_kawai(), caugi_layout_sugiyama(), caugi_plot(), divide-caugi_plot-caugi_plot, plot()

Examples

# Create a three-tier causal graph (exposures -> mediators -> outcome)
cg <- caugi(
  X1 %-->% M1 + M2,
  X2 %-->% M1 + M2,
  M1 %-->% Y,
  M2 %-->% Y
)

# Option 1: Named list (tier names are just labels)
tiers <- list(
  exposures = c("X1", "X2"),
  mediators = c("M1", "M2"),
  outcome = "Y"
)
layout_rows <- caugi_layout_tiered(cg, tiers, orientation = "rows")

# Option 2: Named numeric vector (0-indexed or 1-indexed both work)
tiers <- c(X1 = 1, X2 = 1, M1 = 2, M2 = 2, Y = 3)
layout_cols <- caugi_layout_tiered(cg, tiers, orientation = "columns")

# Option 3: Data.frame
tiers <- data.frame(
  name = c("X1", "X2", "M1", "M2", "Y"),
  tier = c(1, 1, 2, 2, 3)
)
layout <- caugi_layout_tiered(cg, tiers, orientation = "rows")

# The layout includes tier information, so plot() works without passing tiers
plot(cg, layout = layout)

Description

An S7 object that wraps a Mermaid format string for displaying caugi graphs. When printed interactively, displays the Mermaid string cleanly.

Usage

caugi_mermaid(content)

Arguments

See Also

Other export: caugi_deserialize(), caugi_dot(), caugi_export(), caugi_graphml(), caugi_serialize(), export-classes, format-caugi, format-dot, format-graphml, format-mermaid, knit_print.caugi_export, read_caugi(), read_graphml(), to_dot(), to_graphml(), to_mermaid(), write_caugi(), write_dot(), write_graphml(), write_mermaid()

Description

Configure global defaults for caugi, including plot composition spacing and default visual styles for nodes, edges, labels, and titles.

Usage

caugi_options(...)

Arguments

Details

The use_open_graph_definition option (TRUE/FALSE, default TRUE) controls how graph queries interpret reachability relations. When TRUE (open definition), queries such as ancestors(), descendants(), posteriors(),and anteriors() exclude the queried node itself. When FALSE (closed definition), the queried node is included in the results.

The plot options are nested under the plot key:

• spacing: A grid::unit() controlling space between composed plots (default: grid::unit(1, "lines"))

• node_style: List of default node appearance parameters:

  • fill: Fill color (default: "lightgrey")

  • padding: Padding around labels in mm (default: 2)

  • size: Size multiplier (default: 1)

• edge_style: List of default edge appearance parameters:

  • arrow_size: Arrow size in mm (default: 3)

  • circle_size: Radius of endpoint circles for partial edges in mm (default: 1.5)

  • fill: Arrow/line color (default: "black")

• label_style: List of label text parameters (see grid::gpar())

• title_style: List of title text parameters:

  • col: Text color (default: "black")

  • fontface: Font face (default: "bold")

  • fontsize: Font size in pts (default: 14.4)

Options set via caugi_options() serve as global defaults that can be overridden by arguments to plot().

Value

When setting, returns (invisibly) the previous values for the updated options. When getting (no arguments or unnamed character vector), returns the requested options.

See Also

plot() for per-plot style arguments, grid::gpar() for available graphical parameters

Examples

# Query all options
caugi_options()

# Use closed graph definition
caugi_options(use_open_graph_definition = FALSE)

# Query specific option
caugi_options("plot")

# Query nested option
caugi_options("plot", "tier_style")
caugi_options("plot", "node_style", "fill")

# Set plot spacing
caugi_options(plot = list(spacing = grid::unit(2, "lines")))

# Set default node style
caugi_options(plot = list(
  node_style = list(fill = "lightblue", padding = 3)
))

# Set multiple options at once
caugi_options(plot = list(
  spacing = grid::unit(1.5, "lines"),
  node_style = list(fill = "lightblue", padding = 3),
  edge_style = list(arrow_size = 4, fill = "darkgray"),
  title_style = list(col = "blue", fontsize = 16)
))

# Reset to defaults
caugi_options(caugi_default_options())

Description

An S7 object that wraps a grid gTree for displaying caugi graphs. Similar to ggplot objects, these are created by the plot method but not drawn until explicitly printed or plotted. This allows for returning plot objects from functions and controlling when/where they are displayed.

Usage

caugi_plot(grob = NULL)

Arguments

See Also

Other plotting: add-caugi_plot-caugi_plot, caugi_layout(), caugi_layout_bipartite(), caugi_layout_circle(), caugi_layout_fruchterman_reingold(), caugi_layout_kamada_kawai(), caugi_layout_sugiyama(), caugi_layout_tiered(), divide-caugi_plot-caugi_plot, plot()

Description

Converts a caugi graph to a JSON string in the native caugi format. This is a lower-level function; consider using write_caugi() for writing to files.

Usage

caugi_serialize(x, comment = NULL, tags = NULL)

Arguments

Value

A character string containing the JSON representation.

See Also

Other export: caugi_deserialize(), caugi_dot(), caugi_export(), caugi_graphml(), caugi_mermaid(), export-classes, format-caugi, format-dot, format-graphml, format-mermaid, knit_print.caugi_export, read_caugi(), read_graphml(), to_dot(), to_graphml(), to_mermaid(), write_caugi(), write_dot(), write_graphml(), write_mermaid()

Examples

cg <- caugi(A %-->% B, class = "DAG")
json <- caugi_serialize(cg)
cat(json)

Description

Add, remove, or and set nodes or edges to / from a caugi object. Edges can be specified using expressions with the infix operators. Alternatively, the edges to be added are specified using the from, edge, and to arguments.

Usage

add_edges(cg, ..., from = NULL, edge = NULL, to = NULL, inplace = FALSE)

remove_edges(cg, ..., from = NULL, edge = NULL, to = NULL, inplace = FALSE)

set_edges(cg, ..., from = NULL, edge = NULL, to = NULL, inplace = FALSE)

add_nodes(cg, ..., name = NULL, inplace = FALSE)

remove_nodes(cg, ..., name = NULL, inplace = FALSE)

Arguments

Details

Caugi graph verbs

Value

The updated caugi.

Functions

• add_edges(): Add edges.

• remove_edges(): Remove edges.

• set_edges(): Set edge type for given pair(s).

• add_nodes(): Add nodes.

• remove_nodes(): Remove nodes.

See Also

Other verbs: build()

Examples

# initialize empty graph and build slowly
cg <- caugi(class = "PDAG")

cg <- cg |>
  add_nodes(c("A", "B", "C", "D", "E")) |> # A, B, C, D, E
  add_edges(A %-->% B %-->% C) |> # A --> B --> C, D, E
  set_edges(B %---% C) # A --> B --- C, D, E

cg <- remove_edges(cg, B %---% C) |> # A --> B, C, D, E
  remove_nodes(c("C", "D", "E")) # A --> B

# Graphs are now built lazily when needed
parents(cg, "B") # triggers compilation

Description

Get children of nodes in a graph (nodes with directed edges pointing OUT from the target nodes). This is equivalent to neighbors(cg, nodes, mode = "out").

Usage

children(cg, nodes = NULL, index = NULL)

Arguments

Value

Either a character vector of node names (if a single node is requested) or a list of character vectors (if multiple nodes are requested).

See Also

Other queries: ancestors(), anteriors(), descendants(), districts(), edge_types(), edges(), exogenous(), is_acyclic(), is_admg(), is_ag(), is_caugi(), is_cpdag(), is_dag(), is_empty_caugi(), is_mag(), is_mpdag(), is_pdag(), is_simple(), is_ug(), m_separated(), markov_blanket(), neighbors(), nodes(), parents(), posteriors(), same_nodes(), spouses(), subgraph(), topological_sort()

Examples

cg <- caugi(
  A %-->% B,
  B %-->% C,
  class = "DAG"
)
children(cg, "A") # "B"
children(cg, index = 2) # "C"
children(cg, "B") # "C"
children(cg, c("B", "C"))
#> $B
#> [1] "C"
#>
#> $C
#> NULL

Description

Marginalize variables out of an AG, and/or condition on variables. Depending on the structure, it could produce a graph with directed, bidirected, and undirected edges.

Usage

condition_marginalize(cg, cond_vars = NULL, marg_vars = NULL)

Arguments

Value

A caugi object of class "AG".

References

Definition 4.2.1 in Thomas Richardson. Peter Spirtes. "Ancestral graph Markov models." Ann. Statist. 30 (4) 962 - 1030, August 2002. doi:10.1214/aos/1031689015

See Also

Other operations: dag_from_pdag(), exogenize(), latent_project(), meek_closure(), moralize(), mutate_caugi(), normalize_latent_structure(), skeleton()

Examples

mg <- caugi(
  U %-->% X + Y,
  A %-->% X,
  B %-->% Y,
  class = "DAG"
)

condition_marginalize(mg, marg_vars = "U") # ADMG
condition_marginalize(mg, cond_vars = "U") # DAG

Description

Checks whether every node in X is d-separated from every node in Y given Z in a DAG.

Usage

d_separated(
  cg,
  X = NULL,
  Y = NULL,
  Z = NULL,
  X_index = NULL,
  Y_index = NULL,
  Z_index = NULL
)

Arguments

Value

TRUE if d-separated, FALSE otherwise.

See Also

Other adjustment: adjustment_set(), all_adjustment_sets_admg(), all_backdoor_sets(), is_valid_adjustment_admg(), is_valid_backdoor(), minimal_separator()

Examples

cg <- caugi(
  C %-->% X,
  X %-->% F,
  X %-->% D,
  A %-->% X,
  A %-->% K,
  K %-->% Y,
  D %-->% Y,
  D %-->% G,
  Y %-->% H,
  class = "DAG"
)

d_separated(cg, "X", "Y", Z = c("A", "D")) # TRUE
d_separated(cg, "X", "Y", Z = NULL) # FALSE

Description

Given a Partially Directed Acyclic Graph (PDAG), this function attempts to extend it to a Directed Acyclic Graph (DAG) by orienting the undirected edges while preserving acyclicity and all existing directed edges. The procedure implements the Dor-Tarsi algorithm.

If the PDAG cannot be consistently extended to a DAG, the function will raise an error.

Usage

dag_from_pdag(PDAG)

Arguments

Value

A caugi object of class "DAG" representing a DAG extension of the input PDAG.

References

Dor, D., & Tarsi, M. (1992). "A simple algorithm to construct a consistent extension of a partially directed acyclic graph".

See Also

Other operations: condition_marginalize(), exogenize(), latent_project(), meek_closure(), moralize(), mutate_caugi(), normalize_latent_structure(), skeleton()

Examples

PDAG <- caugi(
  A %---% B,
  B %---% C,
  class = "PDAG"
)
DAG <- dag_from_pdag(PDAG)
edges(DAG)

Description

Get descendants of nodes in a caugi

Usage

descendants(
  cg,
  nodes = NULL,
  index = NULL,
  open = caugi_options("use_open_graph_definition")
)

Arguments

Value

Either a character vector of node names (if a single node is requested) or a list of character vectors (if multiple nodes are requested).

See Also

Other queries: ancestors(), anteriors(), children(), districts(), edge_types(), edges(), exogenous(), is_acyclic(), is_admg(), is_ag(), is_caugi(), is_cpdag(), is_dag(), is_empty_caugi(), is_mag(), is_mpdag(), is_pdag(), is_simple(), is_ug(), m_separated(), markov_blanket(), neighbors(), nodes(), parents(), posteriors(), same_nodes(), spouses(), subgraph(), topological_sort()

Examples

cg <- caugi(
  A %-->% B,
  B %-->% C,
  class = "DAG"
)
descendants(cg, "A") # "B" "C"
descendants(cg, "A", open = FALSE) # "A" "B" "C"
descendants(cg, index = 2) # "C"
descendants(cg, "B") # "C"
descendants(cg, c("B", "C"))
#> $B
#> [1] "C"
#>
#> $C
#> NULL

Description

Get districts (c-components) for all nodes, or for selected nodes in an ADMG/AG. A district is a maximal set of nodes connected via bidirected edges. If both nodes and index are NULL, returns all districts in the graph.

Usage

districts(cg, nodes = NULL, index = NULL, all = NULL)

Arguments

Value

If all districts are requested: a list of character vectors, one per district. If nodes/index are supplied: either a character vector (single target) or a named list of character vectors (multiple targets).

See Also

Other queries: ancestors(), anteriors(), children(), descendants(), edge_types(), edges(), exogenous(), is_acyclic(), is_admg(), is_ag(), is_caugi(), is_cpdag(), is_dag(), is_empty_caugi(), is_mag(), is_mpdag(), is_pdag(), is_simple(), is_ug(), m_separated(), markov_blanket(), neighbors(), nodes(), parents(), posteriors(), same_nodes(), spouses(), subgraph(), topological_sort()

Examples

cg <- caugi(
  A %-->% B,
  A %<->% C,
  D %<->% E,
  class = "ADMG"
)
districts(cg)
# Returns list with districts: {A, C}, {B}, {D, E}
districts(cg, nodes = "A") # Returns c("A", "C")
districts(cg, index = c(1, 4))

Description

Stack two plots vertically with configurable spacing. Compositions can be nested to create complex multi-plot layouts.

Arguments

Details

The spacing between plots is controlled by the global option caugi_options()$plot$spacing, which defaults to grid::unit(1, "lines"). Compositions can be nested arbitrarily:

• p1 / p2 - two plots stacked vertically

• p1 / p2 / p3 - three plots in a column

• (p1 + p2) / p3 - two plots on top, one below

Value

A caugi_plot object containing the composed layout

See Also

caugi_options() for configuring spacing and default styles

Other plotting: add-caugi_plot-caugi_plot, caugi_layout(), caugi_layout_bipartite(), caugi_layout_circle(), caugi_layout_fruchterman_reingold(), caugi_layout_kamada_kawai(), caugi_layout_sugiyama(), caugi_layout_tiered(), caugi_plot(), plot()

Examples

cg1 <- caugi(A %-->% B, B %-->% C)
cg2 <- caugi(X %-->% Y, Y %-->% Z)

p1 <- plot(cg1, main = "Graph 1")
p2 <- plot(cg2, main = "Graph 2")

# Vertical composition
p1 / p2

# Mixed composition
(p1 + p2) / p1

Description

Get the edge types of a caugi.

Usage

edge_types(cg)

Arguments

Value

A character vector of edge types.

See Also

Other queries: ancestors(), anteriors(), children(), descendants(), districts(), edges(), exogenous(), is_acyclic(), is_admg(), is_ag(), is_caugi(), is_cpdag(), is_dag(), is_empty_caugi(), is_mag(), is_mpdag(), is_pdag(), is_simple(), is_ug(), m_separated(), markov_blanket(), neighbors(), nodes(), parents(), posteriors(), same_nodes(), spouses(), subgraph(), topological_sort()

Examples

cg <- caugi(
  A %-->% B,
  B %--o% C,
  C %<->% D,
  D %---% E,
  A %o-o% E,
  class = "UNKNOWN"
)
edge_types(cg) # returns c("-->", "o-o", "--o", "<->", "---")

Description

Get edges of a caugi.

Usage

edges(cg, ...)

E(cg, ...)

Arguments

Value

A data.table with columns from, edge, and to.

See Also

Other queries: ancestors(), anteriors(), children(), descendants(), districts(), edge_types(), exogenous(), is_acyclic(), is_admg(), is_ag(), is_caugi(), is_cpdag(), is_dag(), is_empty_caugi(), is_mag(), is_mpdag(), is_pdag(), is_simple(), is_ug(), m_separated(), markov_blanket(), neighbors(), nodes(), parents(), posteriors(), same_nodes(), spouses(), subgraph(), topological_sort()

Examples

cg <- caugi(
  A %-->% B,
  B %-->% C,
  D,
  class = "DAG"
)
edges(cg) # returns the data.table with columns from, edge, to

Description

Exogenize a graph by removing all ingoing edges to the set of nodes specified (i.e., make the nodes exogenous), as well as joining the parents of the nodes specified to the children of the nodes specified.

Usage

exogenize(cg, nodes)

Arguments

Value

A caugi object representing the exogenized graph.

See Also

Other operations: condition_marginalize(), dag_from_pdag(), latent_project(), meek_closure(), moralize(), mutate_caugi(), normalize_latent_structure(), skeleton()

Examples

cg <- caugi(A %-->% B, class = "DAG")
exogenize(cg, nodes = "B") # A, B

Description

Get all exogenous nodes (nodes with no parents) in a caugi.

Usage

exogenous(cg, undirected_as_parents = FALSE)

Arguments

Value

Either a character vector of node names (if a single node is requested) or a list of character vectors (if multiple nodes are requested).

See Also

Other queries: ancestors(), anteriors(), children(), descendants(), districts(), edge_types(), edges(), is_acyclic(), is_admg(), is_ag(), is_caugi(), is_cpdag(), is_dag(), is_empty_caugi(), is_mag(), is_mpdag(), is_pdag(), is_simple(), is_ug(), m_separated(), markov_blanket(), neighbors(), nodes(), parents(), posteriors(), same_nodes(), spouses(), subgraph(), topological_sort()

Examples

cg <- caugi(
  A %-->% B,
  B %-->% C,
  class = "DAG"
)
exogenous(cg) # "A"

Description

S7 classes for representing caugi graphs in various export formats. These classes provide a common interface for serializing graphs to different text formats like DOT, GraphML, JSON, etc.

Base Class

caugi_export is the base class for all export formats. It provides:

• content property: Character string containing the serialized graph

• format property: Character string indicating the format type

• Common methods: print(), as.character(), knit_print()

Subclasses

• caugi_dot: DOT format for Graphviz visualization

• caugi_mermaid: Mermaid format for web-based visualization

See Also

Other export: caugi_deserialize(), caugi_dot(), caugi_export(), caugi_graphml(), caugi_mermaid(), caugi_serialize(), format-caugi, format-dot, format-graphml, format-mermaid, knit_print.caugi_export, read_caugi(), read_graphml(), to_dot(), to_graphml(), to_mermaid(), write_caugi(), write_dot(), write_graphml(), write_mermaid()

Description

Functions for converting caugi graphs to and from the native caugi JSON format. This format provides efficient, reproducible serialization for saving and sharing caugi graphs.

See Also

Other export: caugi_deserialize(), caugi_dot(), caugi_export(), caugi_graphml(), caugi_mermaid(), caugi_serialize(), export-classes, format-dot, format-graphml, format-mermaid, knit_print.caugi_export, read_caugi(), read_graphml(), to_dot(), to_graphml(), to_mermaid(), write_caugi(), write_dot(), write_graphml(), write_mermaid()

Description

Functions for converting caugi graphs to and from Graphviz DOT format. The DOT format is a plain text graph description language used by Graphviz tools for visualization.

See Also

Other export: caugi_deserialize(), caugi_dot(), caugi_export(), caugi_graphml(), caugi_mermaid(), caugi_serialize(), export-classes, format-caugi, format-graphml, format-mermaid, knit_print.caugi_export, read_caugi(), read_graphml(), to_dot(), to_graphml(), to_mermaid(), write_caugi(), write_dot(), write_graphml(), write_mermaid()

Description

Functions for converting caugi graphs to and from GraphML format. GraphML is an XML-based file format for graphs supported by many graph tools and libraries.

See Also

Other export: caugi_deserialize(), caugi_dot(), caugi_export(), caugi_graphml(), caugi_mermaid(), caugi_serialize(), export-classes, format-caugi, format-dot, format-mermaid, knit_print.caugi_export, read_caugi(), read_graphml(), to_dot(), to_graphml(), to_mermaid(), write_caugi(), write_dot(), write_graphml(), write_mermaid()

Description

Functions for converting caugi graphs to Mermaid flowchart format. Mermaid is a JavaScript-based diagramming tool that renders in web browsers and is natively supported by Quarto, GitHub, and many other platforms.

See Also

Other export: caugi_deserialize(), caugi_dot(), caugi_export(), caugi_graphml(), caugi_mermaid(), caugi_serialize(), export-classes, format-caugi, format-dot, format-graphml, knit_print.caugi_export, read_caugi(), read_graphml(), to_dot(), to_graphml(), to_mermaid(), write_caugi(), write_dot(), write_graphml(), write_mermaid()

Description

Sample a random DAG or CPDAG using Erdős-Rényi for random graph generation.

Usage

generate_graph(n, m = NULL, p = NULL, class = c("DAG", "CPDAG"), seed = NULL)

Arguments

Value

The sampled caugi object. class = "DAG" returns a "DAG"; class = "CPDAG" returns an "MPDAG".

See Also

Other simulation functions: simulate_data()

Examples

# generate a random DAG with 5 nodes and 4 edges
dag <- generate_graph(n = 5, m = 4, class = "DAG")

# generate a random CPDAG with 5 nodes and edge probability 0.3
# (returned as an MPDAG)
mpdag <- generate_graph(n = 5, p = 0.3, class = "CPDAG")

Description

Compute the Hamming Distance between two graphs.

Usage

hd(cg1, cg2, normalized = FALSE)

Arguments

Value

An integer representing the Hamming Distance between the two graphs, if normalized = FALSE, or a numeric between 0 and 1 if normalized = TRUE.

See Also

Other metrics: aid(), shd()

Examples

cg1 <- caugi(A %-->% B %-->% C, D %-->% C, class = "DAG")
cg2 <- caugi(A %-->% B %-->% C, D %---% C, class = "PDAG")
hd(cg1, cg2) # 0

Description

Checks if the given caugi graph is acyclic.

Usage

is_acyclic(cg, force_check = FALSE)

Arguments

Details

Logically, it should not be possible to have a graph class of "DAG", "PDAG", or "MPDAG" that has cycles, but in case the user modified the graph after creation in some unforeseen way that could have introduced cycles, this function allows to force a check of acyclicity, if needed.

Value

A logical value indicating whether the graph is acyclic.

See Also

Other queries: ancestors(), anteriors(), children(), descendants(), districts(), edge_types(), edges(), exogenous(), is_admg(), is_ag(), is_caugi(), is_cpdag(), is_dag(), is_empty_caugi(), is_mag(), is_mpdag(), is_pdag(), is_simple(), is_ug(), m_separated(), markov_blanket(), neighbors(), nodes(), parents(), posteriors(), same_nodes(), spouses(), subgraph(), topological_sort()

Examples

cg_acyclic <- caugi(
  A %-->% B,
  B %-->% C,
  class = "DAG"
)
is_acyclic(cg_acyclic) # TRUE
cg_cyclic <- caugi(
  A %-->% B,
  B %-->% C,
  C %-->% A,
  class = "UNKNOWN"
)
is_acyclic(cg_cyclic) # FALSE

Description

Checks if the given caugi graph is an Acyclic Directed Mixed Graph (ADMG).

An ADMG contains only directed (⁠-->⁠) and bidirected (⁠<->⁠) edges, and the directed part must be acyclic.

Usage

is_admg(cg, force_check = FALSE)

Arguments

Value

A logical value indicating whether the graph is an ADMG.

See Also

Other queries: ancestors(), anteriors(), children(), descendants(), districts(), edge_types(), edges(), exogenous(), is_acyclic(), is_ag(), is_caugi(), is_cpdag(), is_dag(), is_empty_caugi(), is_mag(), is_mpdag(), is_pdag(), is_simple(), is_ug(), m_separated(), markov_blanket(), neighbors(), nodes(), parents(), posteriors(), same_nodes(), spouses(), subgraph(), topological_sort()

Examples

cg_admg <- caugi(
  A %-->% B,
  A %<->% C,
  class = "ADMG"
)
is_admg(cg_admg) # TRUE

cg_dag <- caugi(
  A %-->% B,
  class = "DAG"
)
is_admg(cg_dag) # TRUE (DAGs are valid ADMGs)

Description

Checks if the given caugi graph is an Ancestral Graph (AG).

An AG contains directed (⁠-->⁠), bidirected (⁠<->⁠), and undirected (⁠---⁠) edges, and must satisfy ancestral graph constraints (no directed cycles, anterior constraint, and undirected constraint).

Usage

is_ag(cg, force_check = FALSE)

Arguments

Value

A logical value indicating whether the graph is an AG.

See Also

Other queries: ancestors(), anteriors(), children(), descendants(), districts(), edge_types(), edges(), exogenous(), is_acyclic(), is_admg(), is_caugi(), is_cpdag(), is_dag(), is_empty_caugi(), is_mag(), is_mpdag(), is_pdag(), is_simple(), is_ug(), m_separated(), markov_blanket(), neighbors(), nodes(), parents(), posteriors(), same_nodes(), spouses(), subgraph(), topological_sort()

Examples

cg_ag <- caugi(
  A %-->% B,
  C %<->% D,
  E %---% F,
  class = "AG"
)
is_ag(cg_ag) # TRUE

cg_ug <- caugi(
  A %---% B,
  class = "UG"
)
is_ag(cg_ug) # TRUE (UGs are valid AGs)

Description

Checks if the given object is a caugi. Mostly used internally to validate inputs.

Usage

is_caugi(x, throw_error = FALSE)

Arguments

Value

A logical value indicating whether the object is a caugi.

See Also

Other queries: ancestors(), anteriors(), children(), descendants(), districts(), edge_types(), edges(), exogenous(), is_acyclic(), is_admg(), is_ag(), is_cpdag(), is_dag(), is_empty_caugi(), is_mag(), is_mpdag(), is_pdag(), is_simple(), is_ug(), m_separated(), markov_blanket(), neighbors(), nodes(), parents(), posteriors(), same_nodes(), spouses(), subgraph(), topological_sort()

Examples

cg <- caugi(
  A %-->% B,
  class = "DAG"
)

is_caugi(cg) # TRUE

Description

Checks if the given caugi graph is a Complete Partially Directed Acyclic Graph (CPDAG).

Usage

is_cpdag(cg)

Arguments

Value

A logical value indicating whether the graph is a CPDAG.

References

C. Meek (1995). Causal inference and causal explanation with background knowledge. In Proceedings of the Eleventh Conference on Uncertainty in Artificial Intelligence (UAI-95), pp. 403–411. Morgan Kaufmann.

See Also

Other queries: ancestors(), anteriors(), children(), descendants(), districts(), edge_types(), edges(), exogenous(), is_acyclic(), is_admg(), is_ag(), is_caugi(), is_dag(), is_empty_caugi(), is_mag(), is_mpdag(), is_pdag(), is_simple(), is_ug(), m_separated(), markov_blanket(), neighbors(), nodes(), parents(), posteriors(), same_nodes(), spouses(), subgraph(), topological_sort()

Examples

cg_cpdag <- caugi(
  A %---% B,
  A %-->% C,
  B %-->% C,
  class = "PDAG"
)
is_cpdag(cg_cpdag) # TRUE

cg_not_cpdag <- caugi(
  A %---% B,
  A %---% C,
  B %-->% C,
  class = "PDAG"
)
is_cpdag(cg_not_cpdag) # FALSE

Description

Checks if the given caugi graph is a Directed Acyclic Graph (DAG).

Usage

is_dag(cg, force_check = FALSE)

Arguments

Value

A logical value indicating whether the graph is a DAG.

See Also

Other queries: ancestors(), anteriors(), children(), descendants(), districts(), edge_types(), edges(), exogenous(), is_acyclic(), is_admg(), is_ag(), is_caugi(), is_cpdag(), is_empty_caugi(), is_mag(), is_mpdag(), is_pdag(), is_simple(), is_ug(), m_separated(), markov_blanket(), neighbors(), nodes(), parents(), posteriors(), same_nodes(), spouses(), subgraph(), topological_sort()

Examples

cg_dag_class <- caugi(
  A %-->% B,
  class = "DAG"
)
is_dag(cg_dag_class) # TRUE
cg_dag_but_pdag_class <- caugi(
  A %-->% B,
  class = "PDAG"
)
is_dag(cg_dag_but_pdag_class) # TRUE
cg_cyclic <- caugi(
  A %-->% B,
  B %-->% C,
  C %-->% A,
  class = "UNKNOWN",
  simple = FALSE
)
is_dag(cg_cyclic) # FALSE

cg_undirected <- caugi(
  A %---% B,
  class = "UNKNOWN"
)
is_dag(cg_undirected) # FALSE

Description

Checks if the given caugi graph is empty (has no nodes).

Usage

is_empty_caugi(cg)

Arguments

Value

A logical value indicating whether the graph is empty.

See Also

Other queries: ancestors(), anteriors(), children(), descendants(), districts(), edge_types(), edges(), exogenous(), is_acyclic(), is_admg(), is_ag(), is_caugi(), is_cpdag(), is_dag(), is_mag(), is_mpdag(), is_pdag(), is_simple(), is_ug(), m_separated(), markov_blanket(), neighbors(), nodes(), parents(), posteriors(), same_nodes(), spouses(), subgraph(), topological_sort()

Examples

cg_empty <- caugi(class = "DAG")
is_empty_caugi(cg_empty) # TRUE
cg_non_empty <- caugi(
  A %-->% B,
  class = "DAG"
)
is_empty_caugi(cg_non_empty) # FALSE

cg_no_edges_but_has_nodes <- caugi(
  A, B,
  class = "DAG"
)
is_empty_caugi(cg_no_edges_but_has_nodes) # FALSE

Description

Checks if the given caugi graph is a Maximal Ancestral Graph (MAG).

A MAG is an ancestral graph where no additional edge can be added without violating the ancestral graph constraints or changing the encoded independence model.

Usage

is_mag(cg, force_check = FALSE)

Arguments

Value

A logical value indicating whether the graph is a MAG.

See Also

Other queries: ancestors(), anteriors(), children(), descendants(), districts(), edge_types(), edges(), exogenous(), is_acyclic(), is_admg(), is_ag(), is_caugi(), is_cpdag(), is_dag(), is_empty_caugi(), is_mpdag(), is_pdag(), is_simple(), is_ug(), m_separated(), markov_blanket(), neighbors(), nodes(), parents(), posteriors(), same_nodes(), spouses(), subgraph(), topological_sort()

Examples

cg_ag <- caugi(
  A %-->% B,
  B %-->% C,
  class = "AG"
)
is_mag(cg_ag) # TRUE (0 and 2 are m-separated by {B})

Description

Checks if the given caugi graph is a Maximally oriented Partially Directed Acyclic Graph (MPDAG), i.e. a PDAG where no additional edge orientations are implied by Meek's rules (R1–R4).

Usage

is_mpdag(cg)

Arguments

Details

If the graph is not PDAG-compatible, the function returns FALSE.

Value

A logical value indicating whether the graph is an MPDAG.

References

C. Meek (1995). Causal inference and causal explanation with background knowledge. In Proceedings of the Eleventh Conference on Uncertainty in Artificial Intelligence (UAI-95), pp. 403–411. Morgan Kaufmann.

See Also

Other queries: ancestors(), anteriors(), children(), descendants(), districts(), edge_types(), edges(), exogenous(), is_acyclic(), is_admg(), is_ag(), is_caugi(), is_cpdag(), is_dag(), is_empty_caugi(), is_mag(), is_pdag(), is_simple(), is_ug(), m_separated(), markov_blanket(), neighbors(), nodes(), parents(), posteriors(), same_nodes(), spouses(), subgraph(), topological_sort()

Examples

cg_not_mpdag <- caugi(
  A %---% B,
  A %-->% C,
  C %-->% B,
  class = "PDAG"
)
is_mpdag(cg_not_mpdag) # FALSE

Description

Checks if the given caugi graph is a Partially Directed Acyclic Graph (PDAG).

Usage

is_pdag(cg, force_check = FALSE)

Arguments

Value

A logical value indicating whether the graph is a PDAG.

See Also

Other queries: ancestors(), anteriors(), children(), descendants(), districts(), edge_types(), edges(), exogenous(), is_acyclic(), is_admg(), is_ag(), is_caugi(), is_cpdag(), is_dag(), is_empty_caugi(), is_mag(), is_mpdag(), is_simple(), is_ug(), m_separated(), markov_blanket(), neighbors(), nodes(), parents(), posteriors(), same_nodes(), spouses(), subgraph(), topological_sort()

Examples

cg_dag_class <- caugi(
  A %-->% B,
  class = "DAG"
)
is_pdag(cg_dag_class) # TRUE
cg_dag_but_pdag_class <- caugi(
  A %-->% B,
  class = "PDAG"
)
is_pdag(cg_dag_but_pdag_class) # TRUE
cg_cyclic <- caugi(
  A %-->% B,
  B %-->% C,
  C %-->% A,
  D %---% A,
  class = "UNKNOWN",
  simple = FALSE
)
is_pdag(cg_cyclic) # FALSE

cg_undirected <- caugi(
  A %---% B,
  class = "UNKNOWN"
)
is_pdag(cg_undirected) # TRUE

cg_pag <- caugi(
  A %o->% B,
  class = "UNKNOWN"
)
is_pdag(cg_pag) # FALSE

Description

Checks if the given caugi graph is simple (no self-loops and no parallel edges).

Usage

is_simple(cg, force_check = FALSE)

Arguments

Value

A logical value indicating whether the graph is simple.

See Also

Other queries: ancestors(), anteriors(), children(), descendants(), districts(), edge_types(), edges(), exogenous(), is_acyclic(), is_admg(), is_ag(), is_caugi(), is_cpdag(), is_dag(), is_empty_caugi(), is_mag(), is_mpdag(), is_pdag(), is_ug(), m_separated(), markov_blanket(), neighbors(), nodes(), parents(), posteriors(), same_nodes(), spouses(), subgraph(), topological_sort()

Examples

cg_simple <- caugi(
  A %-->% B,
  class = "DAG"
)
is_simple(cg_simple) # TRUE

cg_nonsimple <- caugi(
  A %-->% B,
  A %<->% B,
  class = "UNKNOWN",
  simple = FALSE
)
is_simple(cg_nonsimple) # FALSE

Description

Checks if the given caugi graph is an undirected graph (UG).

Usage

is_ug(cg, force_check = FALSE)

Arguments

Value

A logical value indicating whether the graph is an UG.

See Also

Other queries: ancestors(), anteriors(), children(), descendants(), districts(), edge_types(), edges(), exogenous(), is_acyclic(), is_admg(), is_ag(), is_caugi(), is_cpdag(), is_dag(), is_empty_caugi(), is_mag(), is_mpdag(), is_pdag(), is_simple(), m_separated(), markov_blanket(), neighbors(), nodes(), parents(), posteriors(), same_nodes(), spouses(), subgraph(), topological_sort()

Examples

cg_ug_class <- caugi(
  A %---% B,
  class = "UG"
)
is_ug(cg_ug_class) # TRUE
cg_not_ug <- caugi(
  A %-->% B,
  class = "DAG"
)
is_ug(cg_not_ug) # FALSE

Description

Checks whether Z is a valid adjustment set for estimating the causal effect of X on Y in an ADMG using the generalized adjustment criterion.

Usage

is_valid_adjustment_admg(
  cg,
  X = NULL,
  Y = NULL,
  Z = NULL,
  X_index = NULL,
  Y_index = NULL,
  Z_index = NULL
)

Arguments

Value

Logical value indicating if the adjustment set is valid.

See Also

Other adjustment: adjustment_set(), all_adjustment_sets_admg(), all_backdoor_sets(), d_separated(), is_valid_backdoor(), minimal_separator()

Examples

# Classic confounding
cg <- caugi(
  L %-->% X,
  X %-->% Y,
  L %-->% Y,
  class = "ADMG"
)

is_valid_adjustment_admg(cg, X = "X", Y = "Y", Z = NULL) # FALSE
is_valid_adjustment_admg(cg, X = "X", Y = "Y", Z = "L") # TRUE

Description

Checks whether Z is a valid backdoor adjustment set for ⁠X --> Y⁠.

Usage

is_valid_backdoor(
  cg,
  X = NULL,
  Y = NULL,
  Z = NULL,
  X_index = NULL,
  Y_index = NULL,
  Z_index = NULL
)

Arguments

Value

Logical value indicating if backdoor is valid or not.

See Also

Other adjustment: adjustment_set(), all_adjustment_sets_admg(), all_backdoor_sets(), d_separated(), is_valid_adjustment_admg(), minimal_separator()

Examples

cg <- caugi(
  C %-->% X,
  X %-->% F,
  X %-->% D,
  A %-->% X,
  A %-->% K,
  K %-->% Y,
  D %-->% Y,
  D %-->% G,
  Y %-->% H,
  class = "DAG"
)

is_valid_backdoor(cg, X = "X", Y = "Y", Z = NULL) # FALSE
is_valid_backdoor(cg, X = "X", Y = "Y", Z = "K") # TRUE
is_valid_backdoor(cg, X = "X", Y = "Y", Z = c("A", "C")) # TRUE

Description

Renders caugi export objects as code blocks in Quarto/R Markdown documents. This method is automatically invoked when an export object is the last expression in a code chunk.

Arguments

Details

This method enables seamless rendering of caugi graphs in Quarto and R Markdown. The code block type is determined by the export format. Simply use an export function (e.g., to_dot(cg)) as the last expression in a chunk with output: asis:

#| output: asis
to_dot(cg)

Value

A knit_asis object for rendering by knitr.

See Also

Other export: caugi_deserialize(), caugi_dot(), caugi_export(), caugi_graphml(), caugi_mermaid(), caugi_serialize(), export-classes, format-caugi, format-dot, format-graphml, format-mermaid, read_caugi(), read_graphml(), to_dot(), to_graphml(), to_mermaid(), write_caugi(), write_dot(), write_graphml(), write_mermaid()

Description

Projects out latent (unobserved) variables from a DAG to produce an Acyclic Directed Mixed Graph (ADMG) over the observed variables.

Usage

latent_project(cg, latents)

Arguments

Value

A caugi object of class "ADMG" containing only the observed variables.

See Also

Other operations: condition_marginalize(), dag_from_pdag(), exogenize(), meek_closure(), moralize(), mutate_caugi(), normalize_latent_structure(), skeleton()

Examples

# DAG with latent confounder U
dag <- caugi(
  U %-->% X,
  U %-->% Y,
  X %-->% Y,
  class = "DAG"
)

# Project out the latent variable
admg <- latent_project(dag, latents = "U")
# Result: X -> Y, X <-> Y (children of U become bidirected-connected)
edges(admg)

# DAG with directed path through latent
dag2 <- caugi(
  X %-->% L,
  L %-->% Y,
  class = "DAG"
)

# Project out the latent variable
admg2 <- latent_project(dag2, latents = "L")
# Result: X -> Y (directed path X -> L -> Y becomes X -> Y)
edges(admg2)

Description

Returns the number of nodes in the graph.

Arguments

Value

An integer representing the number of nodes.

See Also

Other caugi methods: caugi-equality, print()

Examples

cg <- caugi(
  A %-->% B,
  class = "DAG"
)
length(cg) # 2

cg2 <- caugi(
  A %-->% B + C,
  nodes = LETTERS[1:5],
  class = "DAG"
)
length(cg2) # 5

Description

Test whether two sets of nodes are m-separated given a conditioning set in an ancestral graph (AG) or an ADMG.

M-separation generalizes d-separation to AGs/ADMGs and applies to DAGs.

Usage

m_separated(
  cg,
  X = NULL,
  Y = NULL,
  Z = NULL,
  X_index = NULL,
  Y_index = NULL,
  Z_index = NULL
)

Arguments

Value

A logical value; TRUE if X and Y are m-separated given Z.

See Also

Other queries: ancestors(), anteriors(), children(), descendants(), districts(), edge_types(), edges(), exogenous(), is_acyclic(), is_admg(), is_ag(), is_caugi(), is_cpdag(), is_dag(), is_empty_caugi(), is_mag(), is_mpdag(), is_pdag(), is_simple(), is_ug(), markov_blanket(), neighbors(), nodes(), parents(), posteriors(), same_nodes(), spouses(), subgraph(), topological_sort()

Examples

# Classic confounding example
cg <- caugi(
  L %-->% X,
  X %-->% Y,
  L %-->% Y,
  class = "ADMG"
)
m_separated(cg, X = "X", Y = "Y") # FALSE (connected via L)
m_separated(cg, X = "X", Y = "Y", Z = "L") # TRUE (L blocks the path)

Description

Get Markov blanket of nodes in a caugi

Usage

markov_blanket(cg, nodes = NULL, index = NULL)

Arguments