Skip to content

Commit 4b39101

Browse files
frederikfabriciusbjerrefrederikfabriciusbjerre
committed
Add examples to documentation
1 parent 00abed3 commit 4b39101

34 files changed

Lines changed: 1049 additions & 144 deletions

‎R/adjustment.R‎

Lines changed: 96 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,23 @@
1616
#'
1717
#' @returns Logical scalar.
1818
#'
19+
#' @examples
20+
#' cg <- caugi_graph(
21+
#' C %-->% X,
22+
#' X %-->% F,
23+
#' X %-->% D,
24+
#' A %-->% X,
25+
#' A %-->% K,
26+
#' K %-->% Y,
27+
#' D %-->% Y,
28+
#' D %-->% G,
29+
#' Y %-->% H,
30+
#' class = "DAG"
31+
#' )
32+
#'
33+
#' d_separated(cg, "X", "Y", Z = c("A", "D")) # TRUE
34+
#' d_separated(cg, "X", "Y", Z = NULL) # FALSE
35+
#'
1936
#' @family adjustment
2037
#' @concept adjustment
2138
#'
@@ -56,9 +73,28 @@ d_separated <- function(cg,
5673
#' @param X,Y Node names.
5774
#' @param X_index,Y_index Optional numeric 1-based indices.
5875
#' @param type One of `"parents"`, `"backdoor"`, `"optimal"`.
76+
#' The `optimal` option computes the O-set.
5977
#'
6078
#' @returns A tibble with a `name` column (possibly 0 rows).
6179
#'
80+
#' @examples
81+
#' cg <- caugi_graph(
82+
#' C %-->% X,
83+
#' X %-->% F,
84+
#' X %-->% D,
85+
#' A %-->% X,
86+
#' A %-->% K,
87+
#' K %-->% Y,
88+
#' D %-->% Y,
89+
#' D %-->% G,
90+
#' Y %-->% H,
91+
#' class = "DAG"
92+
#' )
93+
#'
94+
#' adjustment_set(cg, "X", "Y", type = "parents") # C, A
95+
#' adjustment_set(cg, "X", "Y", type = "backdoor") # C, A
96+
#' adjustment_set(cg, "X", "Y", type = "optimal") # K
97+
#'
6298
#' @family adjustment
6399
#' @concept adjustment
64100
#'
@@ -68,7 +104,7 @@ adjustment_set <- function(cg,
68104
Y = NULL,
69105
X_index = NULL,
70106
Y_index = NULL,
71-
type = c("parents", "backdoor", "optimal")) {
107+
type = c("optimal", "parents", "backdoor")) {
72108
is_caugi(cg, TRUE)
73109
if (length(X) > 1 || length(Y) > 1 ||
74110
length(X_index) > 1 || length(Y_index) > 1) {
@@ -100,7 +136,25 @@ adjustment_set <- function(cg,
100136
#' @param Z Optional node set for conditioning
101137
#' @param X_index,Y_index,Z_index Optional 1-based indices.
102138
#'
103-
#' @returns Logical scalar.
139+
#' @returns Logical value indicating if backdoor is valid or not.
140+
#'
141+
#' @examples
142+
#' cg <- caugi_graph(
143+
#' C %-->% X,
144+
#' X %-->% F,
145+
#' X %-->% D,
146+
#' A %-->% X,
147+
#' A %-->% K,
148+
#' K %-->% Y,
149+
#' D %-->% Y,
150+
#' D %-->% G,
151+
#' Y %-->% H,
152+
#' class = "DAG"
153+
#' )
154+
#'
155+
#' is_valid_backdoor(cg, X = "X", Y = "Y", Z = NULL) # FALSE
156+
#' is_valid_backdoor(cg, X = "X", Y = "Y", Z = "K") # TRUE
157+
#' is_valid_backdoor(cg, X = "X", Y = "Y", Z = c("A", "C")) # TRUE
104158
#'
105159
#' @family adjustment
106160
#' @concept adjustment
@@ -143,6 +197,46 @@ is_valid_backdoor <- function(cg,
143197
#' @returns A list of character vectors, each an adjustment set
144198
#' (possibly empty).
145199
#'
200+
#' @examples
201+
#' cg <- caugi_graph(
202+
#' C %-->% X,
203+
#' X %-->% F,
204+
#' X %-->% D,
205+
#' A %-->% X,
206+
#' A %-->% K,
207+
#' K %-->% Y,
208+
#' D %-->% Y,
209+
#' D %-->% G,
210+
#' Y %-->% H,
211+
#' class = "DAG"
212+
#' )
213+
#'
214+
#' all_backdoor_sets(cg, X = "X", Y = "Y", max_size = 3L, minimal = FALSE)
215+
#' #> [[1]]
216+
#' #> [1] "A"
217+
#' #>
218+
#' #> [[2]]
219+
#' #> [1] "K"
220+
#' #>
221+
#' #> [[3]]
222+
#' #> [1] "C" "A"
223+
#' #>
224+
#' #> [[4]]
225+
#' #> [1] "C" "K"
226+
#' #>
227+
#' #> [[5]]
228+
#' #> [1] "A" "K"
229+
#' #>
230+
#' #> [[6]]
231+
#' #> [1] "C" "A" "K"
232+
#'
233+
#' all_backdoor_sets(cg, X = "X", Y = "Y", max_size = 3L, minimal = TRUE)
234+
#' #> [[1]]
235+
#' #> [1] "A"
236+
#' #>
237+
#' #> [[2]]
238+
#' #> [1] "K"
239+
#'
146240
#' @family adjustment
147241
#' @concept adjustment
148242
#'

‎R/as_caugi.R‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -40,6 +40,68 @@ Matrix_S4_class <- readRDS("inst/S4_class_definitions/Matrix_class.rds")
4040
#'
4141
#' @returns A `caugi_graph` object.
4242
#'
43+
#' @examples
44+
#' # igraph
45+
#' ig <- igraph::graph_from_literal(A - +B, B - +C)
46+
#' cg_ig <- as_caugi(ig, class = "DAG")
47+
#'
48+
#' # graphNEL
49+
#' gn <- graph::graphNEL(nodes = c("A", "B", "C"), edgemode = "directed")
50+
#' gn <- graph::addEdge("A", "B", gn)
51+
#' gn <- graph::addEdge("B", "C", gn)
52+
#' cg_gn <- as_caugi(gn, class = "DAG")
53+
#'
54+
#' # adjacency matrix
55+
#' m <- matrix(0L, 3, 3, dimnames = list(LETTERS[1:3], LETTERS[1:3]))
56+
#' m["A", "B"] <- 1L
57+
#' m["B", "C"] <- 1L
58+
#' cg_adj <- as_caugi(m, class = "DAG")
59+
#'
60+
#' # bnlearn
61+
#' bn <- bnlearn::model2network("[A][B|A][C|B]")
62+
#' cg_bn <- as_caugi(bn, class = "DAG")
63+
#'
64+
#' # dagitty
65+
#' dg <- dagitty::dagitty("dag {
66+
#' A -> B
67+
#' B -> C
68+
#' }")
69+
#' cg_dg <- as_caugi(dg, class = "DAG")
70+
#'
71+
#' cg <- caugi_graph(A %-->% B %-->% C, class = "DAG")
72+
#'
73+
#' # check that all nodes are equal in all graph objects
74+
#' for (cg_converted in list(cg_ig, cg_gn, cg_adj, cg_bn, cg_dg)) {
75+
#' stopifnot(identical(nodes(cg), nodes(cg_converted)))
76+
#' stopifnot(identical(edges(cg), edges(cg_converted)))
77+
#' }
78+
#'
79+
#' # collapse mutual edges
80+
#' ig2 <- igraph::graph_from_literal(A - +B, B - +A, C - +D)
81+
#' cg2 <- as_caugi(ig2, class = "PDAG", collapse = TRUE, collapse_to = "---")
82+
#'
83+
#' # coded integer matrix for PAGs (pcalg style)
84+
#' nm <- c("A", "B", "C", "D")
85+
#' M <- matrix(0L, 4, 4, dimnames = list(nm, nm))
86+
#'
87+
#' # A --> B
88+
#' M["A", "B"] <- 2L # mark at B end
89+
#' M["B", "A"] <- 3L # mark at A end
90+
#'
91+
#' # A --- C
92+
#' M["A", "C"] <- 3L
93+
#' M["C", "A"] <- 3L
94+
#'
95+
#' # B o-> C
96+
#' M["B", "C"] <- 2L
97+
#' M["C", "B"] <- 1L
98+
#'
99+
#' # C o-o D
100+
#' M["C", "D"] <- 1L
101+
#' M["D", "C"] <- 1L
102+
#'
103+
#' cg <- as_caugi(M, class = "PAG")
104+
#'
43105
#' @family conversion
44106
#' @concept conversion
45107
#'

‎R/caugi_graph.R‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -44,6 +44,53 @@
4444
#' @returns A [`caugi_graph`] S7 object containing the nodes, edges, and a
4545
#' pointer to the underlying Rust graph structure.
4646
#'
47+
#' @examples
48+
#' # create a simple DAG (using NSE)
49+
#' cg <- caugi_graph(
50+
#' A %-->% B + C,
51+
#' B %-->% D,
52+
#' class = "DAG"
53+
#' )
54+
#'
55+
#' # create a PDAG with undirected edges (using NSE)
56+
#' cg2 <- caugi_graph(
57+
#' A %-->% B + C,
58+
#' B %---% D,
59+
#' E, # no neighbors for this node
60+
#' class = "PDAG"
61+
#' )
62+
#'
63+
#' # create a DAG (using SE)
64+
#' cg3 <- caugi_graph(
65+
#' from = c("A", "A", "B"),
66+
#' edge = c("-->", "-->", "-->"),
67+
#' to = c("B", "C", "D"),
68+
#' nodes = c("A", "B", "C", "D", "E"),
69+
#' class = "DAG"
70+
#' )
71+
#'
72+
#' # create a non-simple graph
73+
#' cg4 <- caugi_graph(
74+
#' A %-->% B,
75+
#' B %-->% A,
76+
#' class = "UNKNOWN",
77+
#' simple = FALSE
78+
#' )
79+
#'
80+
#' cg4@simple # FALSE
81+
#' cg4@built # TRUE
82+
#' cg4@graph_class # "UNKNOWN"
83+
#'
84+
#' # create graph, but don't built Rust object yet, which is needed for queries
85+
#' cg5 <- caugi_graph(
86+
#' A %-->% B + C,
87+
#' B %-->% D,
88+
#' class = "DAG",
89+
#' build = FALSE
90+
#' )
91+
#'
92+
#' cg@built # FALSE
93+
#'
4794
#' @family caugi_graph
4895
#' @concept caugi_graph
4996
#'

‎R/caugi_to.R‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,13 @@
55
#'
66
#' @returns An `igraph` object representing the same graph structure.
77
#'
8+
#' @examples
9+
#' cg <- caugi_graph(
10+
#' A %-->% B,
11+
#' class = "DAG"
12+
#' )
13+
#' ig <- as_igraph(cg)
14+
#'
815
#' @family conversion
916
#' @concept conversion
1017
#'
@@ -106,6 +113,13 @@ as_igraph <- function(x, ...) {
106113
#'
107114
#' @returns An integer 0/1 adjacency matrix with row/col names.
108115
#'
116+
#' @examples
117+
#' cg <- caugi_graph(
118+
#' A %-->% B,
119+
#' class = "DAG"
120+
#' )
121+
#' adj <- as_adjacency(cg)
122+
#'
109123
#' @family conversion
110124
#' @concept conversion
111125
#'
@@ -155,6 +169,13 @@ as_adjacency <- function(x) {
155169
#'
156170
#' @returns A `bnlearn` DAG.
157171
#'
172+
#' @examples
173+
#' cg <- caugi_graph(
174+
#' A %-->% B,
175+
#' class = "DAG"
176+
#' )
177+
#' g_bn <- as_bnlearn(cg)
178+
#'
158179
#' @family conversion
159180
#' @concept conversion
160181
#'
@@ -186,6 +207,13 @@ as_bnlearn <- function(x) {
186207
#'
187208
#' @returns A `dagitty` object.
188209
#'
210+
#' @examples
211+
#' cg <- caugi_graph(
212+
#' A %-->% B,
213+
#' class = "DAG"
214+
#' )
215+
#' g_dg <- as_dagitty(cg)
216+
#'
189217
#' @family conversion
190218
#' @concept conversion
191219
#'

‎R/methods.R‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,20 @@
1212
#'
1313
#' @returns An integer representing the number of nodes.
1414
#'
15+
#' @examples
16+
#' cg <- caugi_graph(
17+
#' A %-->% B,
18+
#' class = "DAG"
19+
#' )
20+
#' length(cg) # 2
21+
#'
22+
#' cg2 <- caugi_graph(
23+
#' A %-->% B + C,
24+
#' nodes = LETTERS[1:5],
25+
#' class = "DAG"
26+
#' )
27+
#' length(cg2) # 5
28+
#'
1529
#' @family caugi_graph methods
1630
#' @concept methods
1731
#'
@@ -29,6 +43,14 @@ S7::method(length, caugi_graph) <- function(x) {
2943
#'
3044
#' @returns The input `caugi_graph` object, invisibly.
3145
#'
46+
#' @examples
47+
#' cg <- caugi_graph(
48+
#' A %-->% B + C,
49+
#' nodes = LETTERS[1:5],
50+
#' class = "DAG"
51+
#' )
52+
#' print(cg)
53+
#'
3254
#' @family caugi_graph methods
3355
#' @concept methods
3456
#'

0 commit comments

Comments
 (0)