From bf5ccceba814276aaf8e587c19b1c414fa36ea17 Mon Sep 17 00:00:00 2001 From: Malcolm Barrett Date: Sun, 28 Jan 2024 14:32:41 -0500 Subject: [PATCH] update docs to use `geom_dag()` --- R/canonical.R | 15 +-------------- R/drelationship.R | 15 +-------------- R/geom_dag.R | 5 +++-- R/ggdag.R | 15 +-------------- R/quick_plots.R | 15 +-------------- man/canonicalize.Rd | 35 +++++++++++++++++++-------------- man/d_relationship.Rd | 45 +++++++++++++++++++++++++++++-------------- man/dag_aes.Rd | 1 + man/geom_dag.Rd | 4 ++-- man/ggdag.Rd | 45 +++++++++++++++++++++++++++++-------------- man/quick_plot.Rd | 45 +++++++++++++++++++++++++++++-------------- 11 files changed, 124 insertions(+), 116 deletions(-) diff --git a/R/canonical.R b/R/canonical.R index 5595df6..780e664 100644 --- a/R/canonical.R +++ b/R/canonical.R @@ -8,20 +8,7 @@ #' @param .dag,.tdy_dag input graph, an object of class `tidy_dagitty` or #' `dagitty` #' @param ... additional arguments passed to `tidy_dagitty()` -#' @param edge_type a character vector, the edge geom to use. One of: -#' "link_arc", which accounts for directed and bidirected edges, "link", -#' "arc", or "diagonal" -#' @param node_size size of DAG node -#' @param text_size size of DAG text -#' @param label_size size of label text -#' @param text_col color of DAG text -#' @param label_col color of label text -#' @param node logical. Should nodes be included in the DAG? -#' @param stylized logical. Should DAG nodes be stylized? If so, use -#' `geom_dag_nodes` and if not use `geom_dag_point` -#' @param text logical. Should text be included in the DAG? -#' @param use_labels a string. Variable to use for `geom_dag_label_repel()`. -#' Default is `NULL`. +#' @inheritParams geom_dag #' #' @return a `tidy_dagitty` that includes L or a `ggplot` #' @export diff --git a/R/drelationship.R b/R/drelationship.R index 939d524..235e903 100644 --- a/R/drelationship.R +++ b/R/drelationship.R @@ -11,26 +11,13 @@ #' @param .tdy_dag input graph, an object of class `tidy_dagitty` or #' `dagitty` #' @param ... additional arguments passed to `tidy_dagitty()` -#' @param edge_type a character vector, the edge geom to use. One of: -#' "link_arc", which accounts for directed and bidirected edges, "link", -#' "arc", or "diagonal" #' @param from a character vector, the starting variable (must by in DAG). If #' `NULL`, checks DAG for exposure variable. #' @param to a character vector, the ending variable (must by in DAG). If #' `NULL`, checks DAG for outcome variable. #' @param controlling_for a character vector, variables in the DAG to control #' for. -#' @param node_size size of DAG node -#' @param text_size size of DAG text -#' @param label_size size of label text -#' @param text_col color of DAG text -#' @param label_col color of label text -#' @param node logical. Should nodes be included in the DAG? -#' @param stylized logical. Should DAG nodes be stylized? If so, use -#' `geom_dag_nodes` and if not use `geom_dag_point` -#' @param text logical. Should text be included in the DAG? -#' @param use_labels a string. Variable to use for `geom_dag_label_repel()`. -#' Default is `NULL`. +#' @inheritParams geom_dag #' @param collider_lines logical. Should the plot show paths activated by #' adjusting for a collider? #' @param as_factor logical. Should the `d_relationship` variable be a diff --git a/R/geom_dag.R b/R/geom_dag.R index b305f31..3e31b11 100644 --- a/R/geom_dag.R +++ b/R/geom_dag.R @@ -791,6 +791,7 @@ geom_dag_collider_edges <- function(mapping = NULL, data = NULL, #' DAG aesthetics and any user-specified aesthetics. #' #' @examples +#' library(ggplot2) #' confounder_triangle() %>% #' dag_adjustment_sets() %>% #' ggplot(dag_aes(color = adjusted)) + @@ -821,7 +822,7 @@ dag_aes <- function(...) { #' default, edges, nodes, and text). While the underlying layers, all available #' in ggdag, are true geoms, we usually need a consistent set of layers to make #' a DAG. `geom_dag()` provides this. Because `geom_dag()` is not a true geom, -#' you'll find that it is awkward for sophiticated customizations. When you hit +#' you'll find that it is awkward for sophisticated customization. When you hit #' that point, you should use the underlying geoms directly. #' #' @param size A numeric value scaling the size of all elements in the DAG. This @@ -852,7 +853,7 @@ dag_aes <- function(...) { #' #' @examples #' # Basic usage with ggdag -#' library(ggdag) +#' library(ggplot2) #' dag <- dagify(y ~ x, z ~ y) #' ggplot(dag, dag_aes()) + geom_dag() #' ggplot(dag, dag_aes()) + geom_dag(size = 1.5) diff --git a/R/ggdag.R b/R/ggdag.R index 1949d3d..4db66a2 100644 --- a/R/ggdag.R +++ b/R/ggdag.R @@ -5,20 +5,7 @@ #' @param .tdy_dag input graph, an object of class `tidy_dagitty` or #' `dagitty` #' @param ... additional arguments passed to `tidy_dagitty()` -#' @param edge_type a character vector, the edge geom to use. One of: -#' "link_arc", which accounts for directed and bidirected edges, "link", -#' "arc", or "diagonal" -#' @param node_size size of DAG node -#' @param text_size size of DAG text -#' @param label_size size of label text -#' @param text_col color of DAG text -#' @param label_col color of label text -#' @param node logical. Should nodes be included in the DAG? -#' @param stylized logical. Should DAG nodes be stylized? If so, use -#' `geom_dag_nodes` and if not use `geom_dag_point` -#' @param text logical. Should text be included in the DAG? -#' @param use_labels a string. Variable to use for `geom_dag_label_repel()`. -#' Default is `NULL`. +#' @inheritParams geom_dag #' #' @return a `ggplot` #' @export diff --git a/R/quick_plots.R b/R/quick_plots.R index 8d64a24..f9b3e04 100644 --- a/R/quick_plots.R +++ b/R/quick_plots.R @@ -5,20 +5,7 @@ #' #' @param x,y,a,b,m,z Character vector. Optional label. Default is `NULL` #' @param x_y_associated Logical. Are x and y associated? Default is `FALSE`. -#' @param edge_type a character vector, the edge geom to use. One of: -#' "link_arc", which accounts for directed and bidirected edges, "link", -#' "arc", or "diagonal" -#' @param node_size size of DAG node -#' @param text_size size of DAG text -#' @param label_size size of label text -#' @param text_col color of DAG text -#' @param label_col color of label text -#' @param node logical. Should nodes be included in the DAG? -#' @param stylized logical. Should DAG nodes be stylized? If so, use -#' `geom_dag_nodes` and if not use `geom_dag_point` -#' @param text logical. Should text be included in the DAG? -#' @param use_labels a string. Variable to use for `geom_dag_label_repel()`. -#' Default is `NULL`. +#' @inheritParams geom_dag #' #' @return a DAG of class `dagitty` or a `ggplot` #' @export diff --git a/man/canonicalize.Rd b/man/canonicalize.Rd index 55d948d..cdd6793 100644 --- a/man/canonicalize.Rd +++ b/man/canonicalize.Rd @@ -33,29 +33,36 @@ ggdag_canonical( \item{...}{additional arguments passed to \code{tidy_dagitty()}} -\item{edge_type}{a character vector, the edge geom to use. One of: -"link_arc", which accounts for directed and bidirected edges, "link", -"arc", or "diagonal"} +\item{edge_type}{The type of edge, one of "link_arc", "link", "arc", +"diagonal".} -\item{node_size}{size of DAG node} +\item{node_size}{The size of the nodes.} -\item{text_size}{size of DAG text} +\item{text_size}{The size of the text.} -\item{label_size}{size of label text} +\item{label_size}{The size of the labels.} -\item{text_col}{color of DAG text} +\item{text_col}{The color of the text.} -\item{label_col}{color of label text} +\item{label_col}{The color of the labels.} -\item{use_labels}{a string. Variable to use for \code{geom_dag_label_repel()}. -Default is \code{NULL}.} +\item{use_nodes}{A logical value. Include \code{geom_dag_point()}?} -\item{text}{logical. Should text be included in the DAG?} +\item{use_stylized}{A logical value. Include \code{geom_dag_node()}?} -\item{node}{logical. Should nodes be included in the DAG?} +\item{use_text}{A logical value. Include \code{geom_dag_text()}?} -\item{stylized}{logical. Should DAG nodes be stylized? If so, use -\code{geom_dag_nodes} and if not use \code{geom_dag_point}} +\item{use_labels}{A logical value. Include \code{geom_dag_label_repel()}?} + +\item{label}{The bare name of a column to use for \code{geom_dag_label_repel()}. +If \code{use_labels = TRUE}, the default is to use \code{label}.} + +\item{text}{The bare name of a column to use for \code{geom_dag_text()}. If +\code{use_text = TRUE}, the default is to use \code{name}.} + +\item{node}{Deprecated.} + +\item{stylized}{Deprecated.} } \value{ a \code{tidy_dagitty} that includes L or a \code{ggplot} diff --git a/man/d_relationship.Rd b/man/d_relationship.Rd index 3a39e5a..0202c5b 100644 --- a/man/d_relationship.Rd +++ b/man/d_relationship.Rd @@ -134,29 +134,46 @@ factor?} \item{...}{additional arguments passed to \code{tidy_dagitty()}} -\item{edge_type}{a character vector, the edge geom to use. One of: -"link_arc", which accounts for directed and bidirected edges, "link", -"arc", or "diagonal"} +\item{edge_type}{The type of edge, one of "link_arc", "link", "arc", +"diagonal".} -\item{node_size}{size of DAG node} +\item{size}{A numeric value scaling the size of all elements in the DAG. This +allows you to change the scale of the DAG without changing the proportions.} -\item{text_size}{size of DAG text} +\item{node_size}{The size of the nodes.} -\item{label_size}{size of label text} +\item{text_size}{The size of the text.} -\item{text_col}{color of DAG text} +\item{label_size}{The size of the labels.} -\item{label_col}{color of label text} +\item{text_col}{The color of the text.} -\item{use_labels}{a string. Variable to use for \code{geom_dag_label_repel()}. -Default is \code{NULL}.} +\item{label_col}{The color of the labels.} -\item{text}{logical. Should text be included in the DAG?} +\item{edge_width}{The width of the edges.} -\item{node}{logical. Should nodes be included in the DAG?} +\item{edge_cap}{The size of edge caps (the distance between the arrowheads +and the node borders).} -\item{stylized}{logical. Should DAG nodes be stylized? If so, use -\code{geom_dag_nodes} and if not use \code{geom_dag_point}} +\item{arrow_length}{The length of arrows on edges.} + +\item{use_nodes}{A logical value. Include \code{geom_dag_point()}?} + +\item{use_stylized}{A logical value. Include \code{geom_dag_node()}?} + +\item{use_text}{A logical value. Include \code{geom_dag_text()}?} + +\item{use_labels}{A logical value. Include \code{geom_dag_label_repel()}?} + +\item{label}{The bare name of a column to use for \code{geom_dag_label_repel()}. +If \code{use_labels = TRUE}, the default is to use \code{label}.} + +\item{text}{The bare name of a column to use for \code{geom_dag_text()}. If +\code{use_text = TRUE}, the default is to use \code{name}.} + +\item{node}{Deprecated.} + +\item{stylized}{Deprecated.} \item{collider_lines}{logical. Should the plot show paths activated by adjusting for a collider?} diff --git a/man/dag_aes.Rd b/man/dag_aes.Rd index 33d5dd0..d80fb15 100644 --- a/man/dag_aes.Rd +++ b/man/dag_aes.Rd @@ -21,6 +21,7 @@ additional aesthetics, e.g. \code{color} or \code{shape}, with the default aesth mappings. } \examples{ +library(ggplot2) confounder_triangle() \%>\% dag_adjustment_sets() \%>\% ggplot(dag_aes(color = adjusted)) + diff --git a/man/geom_dag.Rd b/man/geom_dag.Rd index a71d133..27ecc11 100644 --- a/man/geom_dag.Rd +++ b/man/geom_dag.Rd @@ -78,12 +78,12 @@ It is not a true geom in that it adds many types of geoms to the plot (by default, edges, nodes, and text). While the underlying layers, all available in ggdag, are true geoms, we usually need a consistent set of layers to make a DAG. \code{geom_dag()} provides this. Because \code{geom_dag()} is not a true geom, -you'll find that it is awkward for sophiticated customizations. When you hit +you'll find that it is awkward for sophisticated customization. When you hit that point, you should use the underlying geoms directly. } \examples{ # Basic usage with ggdag -library(ggdag) +library(ggplot2) dag <- dagify(y ~ x, z ~ y) ggplot(dag, dag_aes()) + geom_dag() ggplot(dag, dag_aes()) + geom_dag(size = 1.5) diff --git a/man/ggdag.Rd b/man/ggdag.Rd index 5d1263d..ae09f2c 100644 --- a/man/ggdag.Rd +++ b/man/ggdag.Rd @@ -33,29 +33,46 @@ ggdag( \item{...}{additional arguments passed to \code{tidy_dagitty()}} -\item{edge_type}{a character vector, the edge geom to use. One of: -"link_arc", which accounts for directed and bidirected edges, "link", -"arc", or "diagonal"} +\item{size}{A numeric value scaling the size of all elements in the DAG. This +allows you to change the scale of the DAG without changing the proportions.} -\item{node_size}{size of DAG node} +\item{edge_type}{The type of edge, one of "link_arc", "link", "arc", +"diagonal".} -\item{text_size}{size of DAG text} +\item{node_size}{The size of the nodes.} -\item{label_size}{size of label text} +\item{text_size}{The size of the text.} -\item{text_col}{color of DAG text} +\item{label_size}{The size of the labels.} -\item{label_col}{color of label text} +\item{text_col}{The color of the text.} -\item{use_labels}{a string. Variable to use for \code{geom_dag_label_repel()}. -Default is \code{NULL}.} +\item{label_col}{The color of the labels.} -\item{text}{logical. Should text be included in the DAG?} +\item{edge_width}{The width of the edges.} -\item{node}{logical. Should nodes be included in the DAG?} +\item{edge_cap}{The size of edge caps (the distance between the arrowheads +and the node borders).} -\item{stylized}{logical. Should DAG nodes be stylized? If so, use -\code{geom_dag_nodes} and if not use \code{geom_dag_point}} +\item{arrow_length}{The length of arrows on edges.} + +\item{use_nodes}{A logical value. Include \code{geom_dag_point()}?} + +\item{use_stylized}{A logical value. Include \code{geom_dag_node()}?} + +\item{use_text}{A logical value. Include \code{geom_dag_text()}?} + +\item{use_labels}{A logical value. Include \code{geom_dag_label_repel()}?} + +\item{text}{The bare name of a column to use for \code{geom_dag_text()}. If +\code{use_text = TRUE}, the default is to use \code{name}.} + +\item{label}{The bare name of a column to use for \code{geom_dag_label_repel()}. +If \code{use_labels = TRUE}, the default is to use \code{label}.} + +\item{node}{Deprecated.} + +\item{stylized}{Deprecated.} } \value{ a \code{ggplot} diff --git a/man/quick_plot.Rd b/man/quick_plot.Rd index 8c78143..7bbe67b 100644 --- a/man/quick_plot.Rd +++ b/man/quick_plot.Rd @@ -172,29 +172,46 @@ ggdag_mediation_triangle( \item{x_y_associated}{Logical. Are x and y associated? Default is \code{FALSE}.} -\item{edge_type}{a character vector, the edge geom to use. One of: -"link_arc", which accounts for directed and bidirected edges, "link", -"arc", or "diagonal"} +\item{size}{A numeric value scaling the size of all elements in the DAG. This +allows you to change the scale of the DAG without changing the proportions.} -\item{node_size}{size of DAG node} +\item{edge_type}{The type of edge, one of "link_arc", "link", "arc", +"diagonal".} -\item{text_size}{size of DAG text} +\item{node_size}{The size of the nodes.} -\item{label_size}{size of label text} +\item{text_size}{The size of the text.} -\item{text_col}{color of DAG text} +\item{label_size}{The size of the labels.} -\item{label_col}{color of label text} +\item{text_col}{The color of the text.} -\item{use_labels}{a string. Variable to use for \code{geom_dag_label_repel()}. -Default is \code{NULL}.} +\item{label_col}{The color of the labels.} -\item{text}{logical. Should text be included in the DAG?} +\item{edge_width}{The width of the edges.} -\item{node}{logical. Should nodes be included in the DAG?} +\item{edge_cap}{The size of edge caps (the distance between the arrowheads +and the node borders).} -\item{stylized}{logical. Should DAG nodes be stylized? If so, use -\code{geom_dag_nodes} and if not use \code{geom_dag_point}} +\item{arrow_length}{The length of arrows on edges.} + +\item{use_nodes}{A logical value. Include \code{geom_dag_point()}?} + +\item{use_stylized}{A logical value. Include \code{geom_dag_node()}?} + +\item{use_text}{A logical value. Include \code{geom_dag_text()}?} + +\item{use_labels}{A logical value. Include \code{geom_dag_label_repel()}?} + +\item{text}{The bare name of a column to use for \code{geom_dag_text()}. If +\code{use_text = TRUE}, the default is to use \code{name}.} + +\item{label}{The bare name of a column to use for \code{geom_dag_label_repel()}. +If \code{use_labels = TRUE}, the default is to use \code{label}.} + +\item{node}{Deprecated.} + +\item{stylized}{Deprecated.} } \value{ a DAG of class \code{dagitty} or a \code{ggplot}