Merge pull request #8 from ikosmidis/develop

v0.5.2

.Rbuildignore

@@ -7,10 +7,13 @@
 ^codecov\.yml$
 ^CONDUCT\.md$
 README.md
-README_files/.*\.png$
-README_files
+inst/README_files/.*\.png$
+inst/README_files
+inst/README_cache/.*
+inst/README_cache
 README.html
 tests/
+data/
 inst/presentations/
 inst/scratch/
 inst/todo.org
@@ -20,3 +23,4 @@ vignettes/cranly.html
 vignettes/glms.html
 vignettes/cranly.pdf
 vignettes/cranly.html
+^CRAN-RELEASE$

DESCRIPTION

@@ -1,18 +1,19 @@
 Package: cranly
 Title: Package Directives and Collaboration Networks in CRAN
-Version: 0.3
+Version: 0.5.2
 Authors@R: c(person(given = "Ioannis", family = "Kosmidis",
                     role = c("aut", "cre"),
 	            email = "[email protected]",
 		    comment = c(ORCID = "0000-0003-1556-0302")))
-Description: Provides core visualisations and summaries for the CRAN package database. The package provides comprehensive methods for cleaning up and organising the information in the CRAN package database, for building package directives networks (depends, imports, suggests, enhances, linking to) and collaboration networks, producing package dependence trees, and for computing useful summaries and producing interactive visualisations from the resulting networks. The package also provides functions to coerce the networks to 'igraph' <https://CRAN.R-project.org/package=igraph> objects for further analyses and modelling.
+Description: Core visualizations and summaries for the CRAN package database. The package provides comprehensive methods for cleaning up and organizing the information in the CRAN package database, for building package directives networks (depends, imports, suggests, enhances, linking to) and collaboration networks, producing package dependence trees, and for computing useful summaries and producing interactive visualizations from the resulting networks and summaries. The resulting networks can be coerced to 'igraph' <https://CRAN.R-project.org/package=igraph> objects for further analyses and modelling.
 URL: https://github.com/ikosmidis/cranly
 BugReports: https://github.com/ikosmidis/cranly/issues
 Depends: R (>= 3.4.0)
-Imports: visNetwork, colorspace, igraph, magrittr, stringr, ggplot2, countrycode
+Imports: visNetwork, colorspace, igraph, magrittr, stringr, ggplot2, countrycode, wordcloud, tm
 License: GPL-3
 Encoding: UTF-8
 LazyData: true
 RoxygenNote: 6.1.1
 Suggests: knitr, rmarkdown
 VignetteBuilder: knitr
+Roxygen: list(markdown = TRUE)

NAMESPACE

@@ -5,36 +5,80 @@ S3method(author_of,cranly_network)
 S3method(author_with,cranly_network)
 S3method(build_dependence_tree,cranly_network)
 S3method(build_network,cranly_db)
-S3method(depends,cranly_network)
-S3method(enhances,cranly_network)
-S3method(imports,cranly_network)
+S3method(dependency_of,cranly_network)
+S3method(depending_on,cranly_network)
+S3method(description_of,cranly_network)
+S3method(email_of,cranly_network)
+S3method(email_with,cranly_network)
+S3method(enhanced_by,cranly_network)
+S3method(enhancing,cranly_network)
+S3method(imported_by,cranly_network)
+S3method(importing,cranly_network)
+S3method(license_of,cranly_network)
+S3method(linked_by,cranly_network)
 S3method(linking_to,cranly_network)
+S3method(maintained_by,cranly_network)
+S3method(maintainer_of,cranly_network)
 S3method(package_by,cranly_network)
 S3method(package_with,cranly_network)
 S3method(plot,cranly_dependence_tree)
 S3method(plot,cranly_network)
 S3method(plot,summary_cranly_network)
+S3method(release_date_of,cranly_network)
 S3method(subset,cranly_network)
-S3method(suggests,cranly_network)
+S3method(suggested_by,cranly_network)
+S3method(suggesting,cranly_network)
 S3method(summary,cranly_dependence_tree)
 S3method(summary,cranly_network)
+S3method(title_of,cranly_network)
+S3method(version_of,cranly_network)
+S3method(word_cloud,cranly_network)
+S3method(word_cloud,numeric)
 export(author_of)
 export(author_with)
+export(authors_of)
+export(authors_with)
 export(build_dependence_tree)
 export(build_network)
 export(clean_CRAN_db)
 export(clean_up_author)
 export(clean_up_directives)
 export(compute_dependence_tree)
-export(depends)
-export(enhances)
-export(imports)
+export(compute_term_frequency)
+export(dependency_of)
+export(depending_on)
+export(description_of)
+export(descriptions_of)
+export(email_of)
+export(email_with)
+export(emails_of)
+export(emails_with)
+export(enhanced_by)
+export(enhancing)
+export(imported_by)
+export(importing)
+export(license_of)
+export(licenses_of)
+export(linked_by)
 export(linking_to)
+export(maintained_by)
+export(maintainer_of)
 export(package_by)
 export(package_with)
-export(suggests)
+export(packages_by)
+export(packages_with)
+export(release_date_of)
+export(release_dates_of)
+export(suggested_by)
+export(suggesting)
+export(title_of)
+export(titles_of)
+export(version_of)
+export(versions_of)
+export(word_cloud)
 import(countrycode)
 import(igraph)
+import(tm)
 importFrom(ggplot2,coord_flip)
 importFrom(ggplot2,geom_bar)
 importFrom(ggplot2,ggplot)
@@ -49,3 +93,4 @@ importFrom(utils,combn)
 importFrom(utils,head)
 importFrom(utils,installed.packages)
 importFrom(utils,stack)
+importFrom(wordcloud,wordcloud)

NEWS.md

@@ -1,11 +1,38 @@
+# cranly 0.5
+
+## New functionality
+* New extractor functions `suggested_by`, `imported_by`, `dependency_of`, `linked_by`, `enhanced_by`, `suggesting`, `importing`, `linking_to`, `enhancing`, `maintainer_of`, `maintained_by`, `email_of`, `email_with`, `description_of`, `title_of`, `license_of`, `version_of`, `release_date_of`
+* Plural aliases for extractor functions (e.g. `authors_of`, `release_dates_of` and so on)
+* methods for word clouds of titles, description files and author names (see `?word_cloud`)
+* `subset.cranly_network` now has a `maintainer` argument to subset by maintainer
+
+## Bug fixes
+* Fixed a bug where packages with no directives were removed from the network when `perspective = "package"` 
+* Fixed extractor bugs and improved documentation
+* `build_network` now works without explicitly supplying any arguments
+
+## Other improvements, updates and additions
+* Moved to [roxygen2 with rmarkdown](https://cran.r-project.org/package=roxygen2/vignettes/markdown.html)
+* Major documentation updates
+* New improved codebase for extractor functions (see `?extractor-functions`)
+* `date` and `published` in `cranly_db` objects are now of class `Date`
+* extractor functions have a new argument `flat`; if \code{FALSE} then a `data.frame` with all available information on the corresponding matches is returned
+* `cranly_network_objects` with `perspective = "package` carry maintainer and maintainer email information
+* New vignette on extractor functions and word clouds
+* Updated DESCRIPTION file
+
+
+## New functionality
+* New extractor functions: `maintainer_of`, `maintained_by`, `email_of`, `email_with`, `description_of`, `title_of`, `license_of`, `version_of`, `release_date_of` (see `?extractor-functions`)
+
 # cranly 0.3
 
 ## Bug fixes
 * Fixed a minor bug that may return duplicated base packages
 
 ## Other improvements, updates and addition
-* Improved vignettes and fixed check erorrs that resulted in archiving on 2019-01-23
-* Improved documentsation
+* Improved vignettes and fixed check errors that resulted in archiving on 2019-01-23
+* Improved documentation
 * Removed **testthat** from Suggests in DESCRIPTION
 
 # cranly 0.2

R/build_network.R

@@ -1,30 +1,33 @@
-# Copyright (C) 2018 Ioannis Kosmidis
+# Copyright (C) 2018- Ioannis Kosmidis
 
 #' Compute edges and nodes of package directives and collaboration networks
+#' 
+#' @param object a [`cranly_db`] object. If missing (default) a call to [`clean_CRAN_db`] is issued.
+#' @param trace logical. Print progress information? Default is [`FALSE`].
+#' @param perspective character. Should a `"package"` (default) or an `"author"` network be built?
+#' @param ... Currently not used.
 #'
-#' @param object a \code{\link{cranly_db}} object
-#' @param trace logical. Print progress information? Default is \code{FALSE}
-#' @param perspective character. Build a \code{"package"} (default )or an \code{"author"} network?
-#' @param ... Currently not used
-#'
-#' @aliases cranly_network
+#' @aliases cranly_network build_network
 #'
 #' @return
 #'
-#' A list of 2 \code{\link{data.frame}s} with the \code{edges} and
-#' \code{nodes} of the network
+#' A list of 2 [`data.frame`] objects with the `edges` and `nodes` of the network.
 #'
 #' @details
 #'
-#' The convention for a \code{\link{cranly_network}} object with
-#' \code{perspective = "package"} is that the direction of an edge is
+#' The convention for a [`cranly_network`] object with
+#' `perspective = "package"` is that the direction of an edge is
 #' from the package that is imported by, suggested by, enhances or is
 #' a dependency of another package, to the latter package. The author
-#' collaboration network is analysed and visualised as undirected by
-#' all methods in \code{cranly}.
+#' collaboration network is analyzed and visualized as undirected by
+#' all methods in `cranly`.
+#'
+#' 
+#' @seealso
+#' [`clean_CRAN_db`] [`subset.cranly_network`] [`plot.cranly_network`] [`extractor-functions`]
 #'
 #' @examples
-#' \dontrun{
+#' \donttest{
 #' cran_db <- clean_CRAN_db()
 #' ## Package directives network
 #' package_network <- build_network(object = cran_db, perspective = "package")
@@ -42,11 +45,15 @@
 #' }
 #'
 #' @export
-build_network.cranly_db <- function(object = clean_CRAN_db(),
+build_network.cranly_db <- function(object,
                                     trace = FALSE, perspective = "package", ...) {
 
     perspective <- match.arg(perspective, c("package", "author"))
 
+    if (missing(object)) {
+        object <- clean_CRAN_db()
+    }
+
     if (perspective == "package") {
         compute_edges <- function(what = "imports", rev = FALSE) {
             out <- object[[what]]
@@ -62,13 +69,33 @@ build_network.cranly_db <- function(object = clean_CRAN_db(),
         su <- compute_edges(what = "suggests")
         en <- compute_edges(what = "enhances", rev = TRUE)
         de <- compute_edges(what = "depends")
-        li <- compute_edges(what = "linkingto")
+        li <- compute_edges(what = "linking_to")
 
         ## Edges
         edges <- rbind(im, su, en, de, li)
 
+
         nodes <- merge(data.frame(package = unique(c(edges$from, edges$to)), stringsAsFactors=FALSE),
-                       object, by = "package", all.x = TRUE)
+                       object, by = "package", all = TRUE) ## all.x in previous version
+
+        ## NA in enhances, imports etc indicates that no information
+        ## is available about that package (e.g being from
+        ## bioconductor). character(0) on the other hand means that
+        ## there is no package in enhances, imports, etc.
+
+        ## Split name and emails of maintainers
+        maintainers <- lapply(strsplit(nodes$maintainer, "<"), function(x) {
+            gsub(">", "", x)
+        })       
+
+        ## Extract and clean white space
+        nodes$maintainer <- sapply(maintainers, "[", 1) %>%
+            str_replace_all("^\\s+|\\s+$|\\s+(?=\\s)", "") %>%
+            clean_up_author()        
+
+        nodes$email <- sapply(maintainers, "[", 2) %>%
+            str_replace_all("^\\s+|\\s+$|\\s+(?=\\s)", "")
+
 
         base_packages <- utils::installed.packages(priority = "high")
         base_package_names <- unique(base_packages[, "Package"])
@@ -93,7 +120,7 @@ build_network.cranly_db <- function(object = clean_CRAN_db(),
                 d[["suggests"]] <- unname(x["suggests"])
                 d[["enhances"]] <- unname(x["enhances"])
                 d[["depends"]] <- unname(x["depends"])
-                d[["linkingto"]] <- unname(x["linkingto"])
+                d[["linking_to"]] <- unname(x["linking_to"])
                 d[["version"]] <- x$version
                 d[["maintainer"]] <- x$maintainer
                 d
@@ -123,3 +150,6 @@ build_network.cranly_db <- function(object = clean_CRAN_db(),
     out
 
 }
+
+
+build_network.NULL <- build_network.cranly_db