Merge pull request #509 from olivroy/docs

Documentation validation

NEWS.md

@@ -12,7 +12,7 @@
 
 # DiagrammeR 1.0.10
 
-* Remove dependency on the **influenceR** package, which also means removing the `get_constraint()` and `get_bridging()` graph inspection functions.
+* Remove dependency on the **influenceR** package, which also means removing the `get_constraint()` and `get_bridging()` graph inspection functions. (#486)
 
 # DiagrammeR 1.0.9
 
@@ -26,41 +26,76 @@
 
 * Fix malformed CSS selector in `htmlwidgets/grViz.js`
 
-* Only call `replace_na(replace = "")` on character columns
+* Fixes for dev tidyr. Only call `replace_na(replace = "")` on character columns. (@DavisVaughan, #448)
 
-* Added the `envir` argument to the `grViz` and `replace_in_spec` functions.
+* Added the `envir` argument to the `grViz()` and `replace_in_spec()` functions. (@atusy, #408)
 
 # DiagrammeR 1.0.6.1
 
 * Removed the `set_df_as_node_attr()`, `set_df_as_edge_attr()`, and `get_attr_dfs()` functions.
 
 # DiagrammeR 1.0.5
 
-* Removes the ability to save a DiagrammeR graph object as a Gephi file (.gexf) since the **rgexf** package is no longer maintained
+* Removes the ability to save a DiagrammeR graph object as a Gephi file (.gexf) since the **rgexf** package is no longer maintained.
 
 # DiagrammeR 1.0.0
 
 * Added the helper functions `node_aes()`, `node_data()`, `edge_aes()`, and `edge_data()` to facilitate the binding of node and edge aesthetic and data attribute values; several functions now have namesake arguments that accept these functions' output.
 
+* Added traversal functions `trav_in_until()` and `trav_out_until()`.
+
 * Information about the graph is now displayed in the console when the graph object is called
 
-* Error messages are now more helpful and try to provide pointers for the more common errors
+* Error messages are now more helpful and try to provide pointers for the more common errors.
 
-# DiagrammeR 0.9.2
+## Deprecated
 
-* Added functions to generate 2D and 3D grid graphs (`add_grid_2d()` and `add_grid_3d()`)
+* `create_complement_graph()` is deprecated in favor of `create_graph()`  + `transform_to_complement_graph()`.
 
-* Added `_ws` (with selection) variants of the `mutate_[node/edge]_attrs()` functions for mutating node or edge attributes for only those nodes/edges in an active selection
+* `create_subgraph_ws()` is deprecated in favor of `create_graph()` + `transform_to_subgraph_ws()`.
 
-* Incorporated an `edges` argument into the `select_edges()` function in order to filter the selection of edges to a set of edge ID values
+* `edge_rel()` is deprecated in favor of `graph$edges_df$rel` for edge relationships.
 
-* Reduced the dependency on R to version >= 3.2.0
+* `create_random_graph()` is deprecated in favor of `create_graph()` + `add_gnm_graph()`, `add_growing_graph()`, `add_islands_graph()`, `add_smallworld_graph()` for the creation of randomized graphs.
+
+## Functions renamed: (old functions were removed)
+
+* `add_to_series()` -> `add_graph_to_graph_series()`
+* `remove_from_series()` -> `remove_graph_from_graph_series()`
+* `get_graph_from_series()` -> `get_graph_from_graph_series()`
+* `create_series()` -> `create_graph_series()`
+* `subset_series()` -> `filter_graph_series()`
+* `render_graph_from_series()` ->  `render_graph_from_graph_series()`
+* `series_info()` -> `get_graph_series_info()`
+* `graph_count()` -> `count_graphs_in_graph_series()`
+* `graph_info()` -> `get_graph_info()`
+* `node_present()` -> `is_node_present()`
+* `edge_present()` -> `is_edge_present()`
+* `edge_count()` -> `count_edges()`
+* `node_count()` -> `count_nodes()`
+* `edge_info()` -> `get_edge_info()`
+* `node_info()` -> `get_node_info()`
+* `node_type()` -> `get_node_attrs()`
+* `get_global_graph_attrs()` ->  `get_global_graph_attr_info()`
+* `get_min_spanning_tree()` -> `transform_to_min_spanning_tree()`
+
+## Functions removed:
+
+`cache_edge_attrs()`, `cache_edge_attrs_ws()`, `cache_edge_count_ws()`, `cache_node_attrs()`, `cache_node_attrs_ws()`, `cache_node_count_ws()`, `clear_global_graph_attrs()`, `image_icon()`, `set_global_graph_attrs()`.
+
+## Functions added
+
+`add_node_clones_ws()`, `count_loop_edges()`,
+`count_s_connected_cmpts()`, `count_unconnected_nodes()`, `count_w_connected_cmpts()`, 
+`delete_cache()`, `delete_loop_edges_ws()`, `deselect_edges()`, `deselect_nodes()`,
+`fully_connect_nodes_ws()`, `fully_disconnect_nodes_ws()`, `get_edge_df_ws()`,  `get_node_df_ws()`, 
+`is_graph_undirected()`,  `set_graph_directed()`,  `set_edge_attr_to_display()`
 
 # DiagrammeR 0.9.2
 
 * Added functions to generate 2D and 3D grid graphs (`add_grid_2d()` and `add_grid_3d()`)
 
-* Added `_ws` (with selection) variants of the `mutate_[node/edge]_attrs()` functions for mutating node or edge attributes for only those nodes/edges in an active selection
+* Added `_ws()` (with selection) variants of the `mutate_[node/edge]_attrs()` functions for mutating node or edge attributes for only those nodes/edges in an active selection
 
 * Incorporated an `edges` argument into the `select_edges()` function in order to filter the selection of edges to a set of edge ID values
 
@@ -110,7 +145,7 @@
 
 * Several graph generators are available for quickly adding graph primitives to a graph object (`add_balanced_tree()`, `add_cycle()`, `add_full_graph()`, `add_path()`, `add_prism()`, and `add_star()`)
 
-* All traversal functions can now migrate numeric node or edge attribute values to the traversed edges (e.g., `trav_out_edge()`, `trav_in_node()`) by providing an attribute name to `copy_attrs_from`; for those traversal functions where nodes or edges may receive multiple values, one can specify an aggregation type in their `agg` argument (e.g,. `trav_in_node()`, `trav_both_edge()`)
+* All traversal functions can now migrate numeric node or edge attribute values to the traversed edges (e.g., `trav_out_edge()`, `trav_in_node()`) by providing an attribute name to `copy_attrs_from()`; for those traversal functions where nodes or edges may receive multiple values, one can specify an aggregation type in their `agg` argument (e.g,. `trav_in_node()`, `trav_both_edge()`)
 
 * Multiple conditions can be specified for all traversal types and for the `select_nodes()` and `select_edges()` functions, plus, they are much easier to write
 
@@ -178,7 +213,7 @@
 
 # DiagrammeR 0.6
 
-* Added several functions to work with graphs: `create_nodes()`, `create_edges()`, `combine_nodes()`, `combine_edges()`, `scale_nodes()`, `scale_edges()`, `get_nodes()`, `node_info()`, `graphviz_graph()`, `graphviz_render()`, and `graphviz_export()`
+* Added several functions to work with graphs: `create_node_df()`, `create_edges()`, `combine_nodes()`, `combine_edges()`, `scale_nodes()`, `scale_edges()`, `get_nodes()`, `node_info()`, `graphviz_graph()`, `graphviz_render()`, and `graphviz_export()`
 
 * Removed the `graphviz_nodes_edges_df()` and `graphviz_single_df()` functions
 

R/create_edge_df.R

@@ -17,14 +17,14 @@
 #'
 #' An arbitrary number of additional columns containing aesthetic or data
 #' attributes can be part of the edf, so long as they follow the aforementioned
-#' columns.
+#' columns. Some examples are included in [edge_aes()]
 #'
 #' @param from A vector of node ID values from which edges are outbound. The
 #'   vector length must equal that of the `to` vector.
 #' @param to A vector of node ID values to which edges are incoming. The vector
 #'   length must equal that of the `from` vector.
 #' @param rel An optional `rel` label for each edge.
-#' @param ... One or more vectors for associated edge attributes.
+#' @param ... One or more vectors for associated edge attributes. Can be some of [edge_aes()]
 #'
 #' @return An edge data frame (edf).
 #'

R/create_node_df.R

@@ -14,14 +14,13 @@
 #' - `label` (of type `character`)
 #'
 #' An arbitrary number of additional columns containing aesthetic or data
-#' attributes can be part of the ndf, so long as they follow the aforementioned
+#' attributes can be part of the ndf, see [node_aes()] for additional attributes that can be used with ..., so long as they follow the aforementioned
 #' columns.
 #'
 #' @param n The total number of nodes to include in the node data frame.
 #' @param type An optional `type` for each node.
 #' @param label An optional `label` for each node.
-#' @param ... One or more vectors for associated node attributes.
-#'
+#' @param ... Additional attributes. Some are present in [node_aes()]
 #' @return A node data frame (ndf).
 #'
 #' @examples
@@ -67,7 +66,7 @@ create_node_df <- function(
 ) {
 
   check_number_whole(n)
-
+  # FIXME, nothing stopping ae
   type <- type %||% rep(NA_character_, n)
 
   # Expand vectors with single values to fill to

R/print.R

@@ -267,7 +267,7 @@ print.dgr_graph <- function(x, ...) {
     # the graph
     # density_str <-
     #   paste0(
-    #     "density: ", graph_info(x)$dens)
+    #     "density: ", get_graph_info(x)$dens)
 
     header_str <-
       paste0(
@@ -498,7 +498,6 @@ print.dgr_graph <- function(x, ...) {
   info_labels_edge_df_length <- nchar(info_labels["get_edge_df"])[[1]]
   info_labels_selection_length <- nchar(info_labels["get_selection"])[[1]]
   info_labels_cache_length <- nchar(info_labels["get_cache"])[[1]]
-  info_labels_attr_dfs_length <- nchar(info_labels["get_attr_dfs"])[[1]]
   info_labels_global_graph_attrs <- nchar(info_labels["get_global_graph_attr_info"])[[1]]
 
   if (console_width - node_detail_str_1_length - info_labels_node_df_length >= 5) {

R/set_edge_attrs.R

@@ -6,7 +6,7 @@
 #' or more edges.
 #'
 #' @inheritParams render_graph
-#' @param edge_attr The name of the attribute to set.
+#' @param edge_attr The name of the attribute to set. Some examples are located in [edge_aes()]
 #' @param values The values to be set for the chosen attribute for the chosen
 #'   edges.
 #' @param from An optional vector of node IDs from which the edge is outgoing

R/set_node_attrs.R

@@ -6,7 +6,7 @@
 #' or more nodes.
 #'
 #' @inheritParams render_graph
-#' @param node_attr The name of the attribute to set.
+#' @param node_attr The name of the attribute to set. Examples of attributes can be found in [node_aes()].
 #' @param values The values to be set for the chosen attribute for the chosen
 #'   nodes.
 #' @param nodes An optional vector of node IDs for filtering the list of nodes

R/utils.R

@@ -572,8 +572,8 @@ node_creation_functions <- function() {
 #'
 #' @noRd
 node_deletion_functions <- function() {
-
-  c("create_subgraph_ws", "create_complement_graph",
+  # previously, create_subgraph_ws, and create_complement_graph?
+  c("transform_to_subgraph_ws", "transform_to_complement_graph",
     "delete_node", "delete_nodes_ws")
 }
 
@@ -609,8 +609,7 @@ edge_deletion_functions <- function() {
 #'
 #' @noRd
 graph_init_functions <- function() {
-
-  c("create_graph", "create_random_graph",
+  c("create_graph",
     "from_igraph", "from_adj_matrix",
     "import_graph")
 }
@@ -787,7 +786,7 @@ remove_linked_dfs <- function(graph) {
       dplyr::filter(node_edge__ == "node") %>%
       dplyr::select("df_id__") %>%
       dplyr::distinct() %>%
-      dplyr::pull(df_id__) %>%
+      dplyr::pull("df_id__") %>%
       base::setdiff(ndf_df_ids)
 
     # If any stored data frames are associated
@@ -811,7 +810,7 @@ remove_linked_dfs <- function(graph) {
       dplyr::filter(node_edge__ == "edge") %>%
       dplyr::select("df_id__") %>%
       dplyr::distinct() %>%
-      dplyr::pull(df_id__) %>%
+      dplyr::pull("df_id__") %>%
       base::setdiff(edf_df_ids)
 
 

tests/testthat/test-graph_validation.R

@@ -48,8 +48,6 @@ test_that("Using an invalid graph triggers an error.", {
     add_smallworld_graph(invalid_graph)
     add_star(invalid_graph)
     add_reverse_edges_ws(invalid_graph)
-    # clear_global_graph_attrs() does not exist.
-    # clear_global_graph_attrs(invalid_graph)
     clear_selection(invalid_graph)
     colorize_edge_attrs(invalid_graph)
     colorize_node_attrs(invalid_graph)
@@ -259,7 +257,6 @@ test_that("Using an empty graph with trigger an error", {
   expect_error(do_dfs(empty_graph))
   expect_error(fully_connect_nodes_ws(empty_graph))
   expect_error(fully_disconnect_nodes_ws(empty_graph))
-  expect_error(get_attr_dfs(empty_graph))
   expect_error(get_degree_distribution(empty_graph))
   expect_error(get_degree_histogram(empty_graph))
   expect_error(get_eccentricity(empty_graph))

tests/testthat/test-mst.R

@@ -1,4 +1,4 @@
-# Obtaining the minimum spanning tree of a graph")
+# Obtaining the minimum spanning tree of a graph
 
 test_that("the MST algorithm is functional", {