Merge pull request #5 from kevinykuo/feature/cran-resubmit

Address CRAN reviewer comments

Author: kevinykuo

.gitignore

@@ -5,3 +5,4 @@
 demo.R
 derby.log
 log4j.spark.*
+internal

DESCRIPTION

@@ -1,11 +1,17 @@
 Package: graphframes
 Type: Package
-Title: R Interface for GraphFrames
+Title: Interface for 'GraphFrames'
 Version: 0.1.0
-Authors@R: person("Kevin", "Kuo", email = "kevin.kuo@rstudio.com", role = c("aut", "cre"))
+Authors@R: person("Kevin", "Kuo", email = "kevin.kuo@rstudio.com", 
+                  role = c("aut", "cre"), comment = c(ORCID = "0000-0001-7803-7901"))
 Maintainer: Kevin Kuo <kevin.kuo@rstudio.com>
-Description: A sparklyr <https://spark.rstudio.com/> extension that provides an R 
-  interface for GraphFrames <https://graphframes.github.io/>.
+Description: A 'sparklyr' <https://spark.rstudio.com/> extension that provides an R 
+  interface for 'GraphFrames' <https://graphframes.github.io/>. 'GraphFrames' is a package
+  for 'Apache Spark' that provides a DataFrame-based API for working with graphs. Functionality
+  includes motif finding and common graph algorithms, such as PageRank and Breadth-first
+  search.
+URL: https://github.com/rstudio/graphframes
+BugReports: https://github.com/rstudio/graphframes/issues
 License: Apache License 2.0 | file LICENSE
 Encoding: UTF-8
 LazyData: true

R/gf_bfs.R

@@ -8,6 +8,11 @@
 #' @param edge_filter Spark SQL expression specifying edges which may be used in the search.
 #' @template roxlate-gf-dots
 #'
+#' @examples
+#' \dontrun{
+#' g <- gf_friends(sc)
+#' gf_bfs(g, from_expr = "name = 'Esther'", to_expr = "age < 32")
+#' }
 #' @export
 gf_bfs <- function(x,
                    from_expr,

R/gf_connected_components.R

@@ -8,6 +8,13 @@
 #' @param algorithm One of 'graphframes' or 'graphx'.
 #' @param checkpoint_interval Checkpoint interval in terms of number of iterations.
 #' @template roxlate-gf-dots
+#' @examples
+#' \dontrun{
+#' # checkpoint directory is required for gf_connected_components()
+#' spark_set_checkpoint_dir(sc, tempdir())
+#' g <- gf_friends(sc)
+#' gf_connected_components(g)
+#' }
 #' @export
 gf_connected_components <- function(x,
                                     broadcast_threshold = 1000000L,

R/gf_examples.R

@@ -1,5 +1,11 @@
 #' Graph of friends in a social network.
 #'
+#' @examples
+#' \dontrun{
+#' library(sparklyr)
+#' sc <- spark_connect(master = "local")
+#' gf_friends(sc)
+#' }
 #' @template roxlate-gf-sc
 #' @export
 gf_friends <- function(sc) {
@@ -14,6 +20,10 @@ gf_friends <- function(sc) {
 #'   The vertex IDs are 0, 1, ..., n-1, and the edges are (0, 1), (1, 2), ...., (n-2, n-1).
 #' @template roxlate-gf-sc
 #' @param n Size of the graph to return.
+#' @examples
+#' \dontrun{
+#' gf_chain(sc, 5)
+#' }
 #' @export
 gf_chain <- function(sc, n) {
   n <- ensure_scalar_integer(n)
@@ -41,6 +51,11 @@ gf_chain <- function(sc, n) {
 #'   "dst", and "b". Edges are directed, but they should be treated as undirected in
 #'    any algorithms run on this model. Vertex IDs are of the form "i,j". E.g., vertex
 #'    "1,3" is in the second row and fourth column of the grid.
+#'
+#' @examples
+#' \dontrun{
+#' gf_grid_ising_model(sc, 5)
+#' }
 #' @export
 gf_grid_ising_model <- function(sc, n, v_std = 1, e_std = 1) {
   sql_context <- invoke_new(sc, "org.apache.spark.sql.SQLContext", spark_context(sc))
@@ -59,6 +74,11 @@ gf_grid_ising_model <- function(sc, n, v_std = 1, e_std = 1) {
 #'    indexed 0 (the root) and the n other leaf vertices 1, 2, ..., n.
 #' @template roxlate-gf-sc
 #' @param n The number of leaves.
+#'
+#' @examples
+#' \dontrun{
+#' gf_star(sc, 5)
+#' }
 #' @export
 gf_star <- function(sc, n) {
   n <- ensure_scalar_integer(n)
@@ -74,6 +94,11 @@ gf_star <- function(sc, n) {
 #'   connected by a single edge (0->n).
 #' @template roxlate-gf-sc
 #' @param blob_size The size of each blob.
+#'
+#' @examples
+#' \dontrun{
+#' gf_two_blobs(sc, 3)
+#' }
 #' @export
 gf_two_blobs <- function(sc, blob_size) {
   blob_size <- ensure_scalar_integer(blob_size)

R/gf_interface.R

@@ -34,6 +34,21 @@ new_graphframe <- function(jobj) {
 #'
 #' @param vertices A \code{tbl_spark} representing vertices.
 #' @param edges A \code{tbl_psark} representing edges.
+#'
+#' @examples
+#' \dontrun{
+#' library(sparklyr)
+#' sc <- spark_connect(master = "local", version = "2.1.0")
+#' v_tbl <- sdf_copy_to(
+#'   sc, data.frame(id = 1:3, name = LETTERS[1:3])
+#' )
+#' e_tbl <- sdf_copy_to(
+#'   sc, data.frame(src = c(1, 2, 2), dst = c(2, 1, 3),
+#'                  action = c("love", "hate", "follow"))
+#' )
+#' gf_graphframe(v_tbl, e_tbl)
+#' gf_graphframe(edges = e_tbl)
+#' }
 #' @export
 gf_graphframe <- function(vertices = NULL, edges) {
   sc <- edges %>%
@@ -170,10 +185,25 @@ gf_degrees <- function(x) {
 }
 
 #' Motif finding: Searching the graph for structural patterns
+#'
+#' Motif finding uses a simple Domain-Specific Language (DSL) for
+#'  expressing structural queries. For example,
+#'  gf_find(g, "(a)-[e]->(b); (b)-[e2]->(a)") will search for
+#'  pairs of vertices a,b connected by edges in both directions.
+#'  It will return a DataFrame of all such structures in the graph,
+#'  with columns for each of the named elements (vertices or edges)
+#'  in the motif. In this case, the returned columns will be in
+#'  order of the pattern: "a, e, b, e2."
+#'
 #' @template roxlate-gf-x
 #'
 #' @param pattern pattern specifying a motif to search for
 #'
+#' @examples
+#' \dontrun{
+#' gf_friends(sc) %>%
+#'   gf_find("(a)-[e]->(b); (b)-[e2]->(a)")
+#' }
 #' @export
 gf_find <- function(x, pattern) {
   ensure_scalar_character(pattern)

R/gf_lpa.R

@@ -11,6 +11,12 @@
 #' @template roxlate-gf-x
 #' @param max_iter Maximum number of iterations.
 #' @template roxlate-gf-dots
+#'
+#' @examples
+#' \dontrun{
+#' g <- gf_friends(sc)
+#' gf_lpa(g, max_iter = 5)
+#' }
 #' @export
 gf_lpa <- function(x, max_iter, ...) {
   max_iter <- ensure_scalar_integer(max_iter)

R/gf_pagerank.R

@@ -6,6 +6,12 @@
 #' @param max_iter Maximum number of iterations.
 #' @param source_id (Optional) Source vertex for a personalized pagerank.
 #' @template roxlate-gf-dots
+#'
+#' @examples
+#' \dontrun{
+#' g <- gf_friends(sc)
+#' gf_pagerank(g, reset_probability = 0.15, tol = 0.01)
+#' }
 #' @export
 gf_pagerank <- function(x, tol = NULL, reset_probability = 0.15, max_iter = NULL,
                         source_id = NULL, ...) {

R/gf_scc.R

@@ -6,6 +6,12 @@
 #' @template roxlate-gf-x
 #' @param max_iter Maximum number of iterations.
 #' @template roxlate-gf-dots
+#'
+#' @examples
+#' \dontrun{
+#' g <- gf_friends(sc)
+#' gf_scc(g, max_iter = 10)
+#' }
 #' @export
 gf_scc <- function(x, max_iter, ...) {
   max_iter <- ensure_scalar_integer(max_iter)

R/gf_shortest_paths.R

@@ -6,6 +6,12 @@
 #' @template roxlate-gf-x
 #' @param landmarks IDs of landmark vertices.
 #' @template roxlate-gf-dots
+#'
+#' @examples
+#' \dontrun{
+#' g <- gf_friends(sc)
+#' gf_shortest_paths(g, landmarks = c("a", "d"))
+#' }
 #' @export
 gf_shortest_paths <- function(x, landmarks, ...) {
   landmarks <- lapply(landmarks, ensure_scalar_character)