update all docs with @dvantwisk suggestions; tests pass; bump

egonw · Apr 9, 2018 · 8b8b710 · 8b8b710
1 parent eeffa83
commit 8b8b710
Show file tree

Hide file tree

Showing 58 changed files with 211 additions and 165 deletions.
diff --git a/.gitignore b/.gitignore
@@ -4,3 +4,4 @@
 .Rhistory
 .RData
 .Ruserdata
+rwikipathways.Rproj
diff --git a/DESCRIPTION b/DESCRIPTION
@@ -1,8 +1,8 @@
 Package: rWikiPathways
 Type: Package
 Title: rWikiPathways - R client library for the WikiPathways API
-Version: 0.99.4
-Date: 2018-04-05
+Version: 0.99.5
+Date: 2018-04-09
 Authors@R: c(person("Egon", "Willighagen", role = c("aut","cre"),
                      email = "egon.willighagen@gmail.com",
                      comment = c(ORCID = "0000-0001-7542-0286")),

diff --git a/NAMESPACE b/NAMESPACE
@@ -38,6 +38,7 @@ export(listPathwayIds)
 export(listPathwayNames)
 export(listPathwayUrls)
 export(listPathways)
+export(wikipathwaysAPI)
 export(wikipathwaysGET)
 importFrom(RJSONIO,fromJSON)
 importFrom(caTools,base64decode)

diff --git a/R/downloadPathwayArchive.R b/R/downloadPathwayArchive.R
@@ -5,8 +5,8 @@
 #' @details If you specify an archive date, organism and format, then the archive file
 #' will be downloaded. Otherwise, the archive will be opened in a tab in your
 #' default browser.
-#' @param date (optional) The timestamp for a monthly release or "current" (default) for 
-#' latest release.
+#' @param date (optional) The timestamp for a monthly release (e.g., 20171010) 
+#' or "current" (default) for latest release.
 #' @param organism (optional) A particular species. See \link{listOrganisms}. 
 #' @param format (optional) Either gpml (default), gmt or svg.
 #' @return Downloaded file or tab in default browser
@@ -18,9 +18,9 @@
 #' }
 #' @export
 #' @importFrom utils browseURL download.file
-downloadPathwayArchive <- function(date='current',organism = NULL, format='gpml'){
-    #validate format
-    match.arg(format, c('gpml','gmt', 'svg'))
+downloadPathwayArchive <- function(date='current',organism = NULL, format=c('gpml', 'gmt', 'svg')){
+    #get validated format
+    format <- match.arg(format)
 
     #validate date
     if (date != 'current')

diff --git a/R/findPathwayByText.R b/R/findPathwayByText.R
@@ -2,8 +2,8 @@
 #' @title Find Pathways By Text
 #'
 #' @description Retrieve a list of pathways containing the query text.
-#' @param query The string to search for, e.g., "cancer"
-#' @return List of lists
+#' @param query A \code{character} string to search for, e.g., "cancer"
+#' @return A \code{list} of lists
 #' @examples {
 #' findPathwaysByText('cancer')
 #' }
@@ -18,8 +18,8 @@ findPathwaysByText <- function(query) {
 #' @title Find Pathway WPIDs By Text 
 #'
 #' @description Retrieve list of pathway WPIDs containing the query text.
-#' @param query The string to search for, e.g., "cancer"
-#' @return List of WPIDs
+#' @param query A \code{character} string to search for, e.g., "cancer"
+#' @return A \code{list} of WPIDs
 #' @examples {
 #' findPathwayIdsByText('cancer')
 #' }
@@ -34,8 +34,8 @@ findPathwayIdsByText <- function(query) {
 #' @description Retrieve list of pathway names containing the query text.
 #' @details Note: there will be multiple listings of the same pathway name if 
 #' copies exist for multiple species.
-#' @param query The string to search for, e.g., "cancer"
-#' @return List of lists
+#' @param query A \code{character} string to search for, e.g., "cancer"
+#' @return A \code{list} of lists
 #' @examples {
 #' findPathwayNamesByText('cancer')
 #' }
@@ -48,8 +48,8 @@ findPathwayNamesByText <- function(query) {
 #' @title Find Pathway URLs By Text 
 #'
 #' @description Retrieve list of pathway URLs containing the query text.
-#' @param query The string to search for, e.g., "cancer"
-#' @return List of lists
+#' @param query A \code{character} string to search for, e.g., "cancer"
+#' @return A \code{list} of lists
 #' @examples {
 #' findPathwayUrlsByText('cancer')
 #' }

diff --git a/R/findPathwaysByLiterature.R b/R/findPathwaysByLiterature.R
@@ -2,8 +2,8 @@
 #' @title Find Pathways By Literature
 #'
 #' @description Retrieve a list of pathways containing the query citation.
-#' @param query The string to search for, e.g., a PMID, title keyword or author name.
-#' @return List of lists
+#' @param query The \code{character} string to search for, e.g., a PMID, title keyword or author name.
+#' @return A \code{list} of lists
 #' @examples {
 #' findPathwaysByLiterature('19649250')
 #' findPathwaysByLiterature('smith')
@@ -20,8 +20,8 @@ findPathwaysByLiterature <- function(query) {
 #' @title Find Pathway WPIDs By Literature 
 #'
 #' @description Retrieve list of pathway WPIDs containing the query citation.
-#' @param query The string to search for, e.g., a PMID, title keyword or author name.
-#' @return List of WPIDs
+#' @param query The \code{character} string to search for, e.g., a PMID, title keyword or author name.
+#' @return A \code{list} of WPIDs
 #' @examples {
 #' findPathwayIdsByLiterature('19649250')
 #' findPathwayIdsByLiterature('smith')
@@ -38,8 +38,8 @@ findPathwayIdsByLiterature <- function(query) {
 #' @description Retrieve list of pathway names containing the query citation.
 #' @details Note: there will be multiple listings of the same pathway name if 
 #' copies exist for multiple species.
-#' @param query The string to search for, e.g., a PMID, title keyword or author name.
-#' @return List of lists
+#' @param query The \code{character} string to search for, e.g., a PMID, title keyword or author name.
+#' @return A \code{list} of lists
 #' @examples {
 #' findPathwayNamesByLiterature('19649250')
 #' findPathwayNamesByLiterature('smith')
@@ -54,8 +54,8 @@ findPathwayNamesByLiterature <- function(query) {
 #' @title Find Pathway URLs By Literature 
 #'
 #' @description Retrieve list of pathway URLs containing the query citation.
-#' @param query The string to search for, e.g., a PMID, title keyword or author name.
-#' @return List of lists
+#' @param query The \code{character} string to search for, e.g., a PMID, title keyword or author name.
+#' @return A \code{list} of lists
 #' @examples {
 #' findPathwayUrlsByLiterature('19649250')
 #' findPathwayUrlsByLiterature('smith')

diff --git a/R/findPathwaysByXref.R b/R/findPathwaysByXref.R
@@ -5,11 +5,11 @@
 #'  and system code.
 #' @details Note: there will be multiple listings of the same pathway if the Xref
 #' is present mutiple times.
-#' @param identifier The official ID specified by a data source or system
-#' @param systemCode The BridgeDb code associated with the data source or system, 
+#' @param identifier (\code{character}) The official ID specified by a data source or system
+#' @param systemCode (\code{character}) The BridgeDb code associated with the data source or system, 
 #' e.g., En (Ensembl), L (Entrez), Ch (HMDB), etc.
 #' See column two of https://github.com/bridgedb/BridgeDb/blob/master/org.bridgedb.bio/resources/org/bridgedb/bio/datasources.txt.
-#' @return List of lists
+#' @return A \code{list} of lists
 #' @examples {
 #' findPathwaysByXref('ENSG00000232810','En')
 #' }
@@ -27,11 +27,11 @@ findPathwaysByXref <- function(identifier, systemCode) {
 #'  and system code.
 #' @details Note: there will be multiple listings of the same pathway if the Xref
 #' is present mutiple times.
-#' @param identifier The official ID specified by a data source or system
-#' @param systemCode The BridgeDb code associated with the data source or system, 
+#' @param identifier (\code{character}) The official ID specified by a data source or system
+#' @param systemCode (\code{character}) The BridgeDb code associated with the data source or system, 
 #' e.g., En (Ensembl), L (Entrez), Ch (HMDB), etc.
 #' See column two of https://github.com/bridgedb/BridgeDb/blob/master/org.bridgedb.bio/resources/org/bridgedb/bio/datasources.txt.
-#' @return List of WPIDs
+#' @return A \code{list} of WPIDs
 #' @examples {
 #' findPathwayIdsByXref('ENSG00000232810','En')
 #' }
@@ -47,11 +47,11 @@ findPathwayIdsByXref <- function(identifier, systemCode) {
 #'  and system code.
 #' @details Note: there will be multiple listings of the same pathway if the Xref
 #' is present mutiple times.
-#' @param identifier The official ID specified by a data source or system
-#' @param systemCode The BridgeDb code associated with the data source or system, 
+#' @param identifier (\code{character}) The official ID specified by a data source or system
+#' @param systemCode (\code{character}) The BridgeDb code associated with the data source or system, 
 #' e.g., En (Ensembl), L (Entrez), Ch (HMDB), etc.
 #' See column two of https://github.com/bridgedb/BridgeDb/blob/master/org.bridgedb.bio/resources/org/bridgedb/bio/datasources.txt.
-#' @return List of lists
+#' @return A \code{list} of lists
 #' @examples {
 #' findPathwayNamesByXref('ENSG00000232810','En')
 #' }
@@ -67,11 +67,11 @@ findPathwayNamesByXref <- function(identifier, systemCode) {
 #'  and system code.
 #' @details Note: there will be multiple listings of the same pathway if the Xref
 #' is present mutiple times.
-#' @param identifier The official ID specified by a data source or system
-#' @param systemCode The BridgeDb code associated with the data source or system, 
+#' @param identifier (\code{character}) The official ID specified by a data source or system
+#' @param systemCode (\code{character}) The BridgeDb code associated with the data source or system, 
 #' e.g., En (Ensembl), L (Entrez), Ch (HMDB), etc.
 #' See column two of https://github.com/bridgedb/BridgeDb/blob/master/org.bridgedb.bio/resources/org/bridgedb/bio/datasources.txt.
-#' @return List of lists
+#' @return A \code{list} of lists
 #' @examples {
 #' findPathwayUrlsByXref('ENSG00000232810','En')
 #' }

diff --git a/R/getColoredPathway.R b/R/getColoredPathway.R
@@ -3,27 +3,29 @@
 #'
 #' @description Retrieve a pathway image file with specified nodes colored by specified colors
 #' @param pathway WikiPathways identifier (WPID) for the pathway to download, e.g. WP4
-#' @param revision (optional) Number to indicate a specific revision to download
-#' @param graphId String or vector indicating the nodes to color (only single values are supported at this time)
+#' @param revision (\code{integer}, optional) Number to indicate a specific revision to download
+#' @param graphId A \code{character} string or \code{vector} indicating the nodes to color (only single values are supported at this time)
 #' @param color (optional) String or vector indicating the highlighting color, e.g., #FF8855.
 #' Default is red. You can provide a single color for mutiple nodes; otherwise
 #' color list and graphId must be the same length.
-#' @param fileType (optional) Image file format
+#' @param fileType (optional) Image file format, e.g., svg (default), png or pdf.
 #' @return Image file
 #' @examples {
-#'   svg = getColoredPathway(pathway="WP554", graphId="ef1f3");
-#'   svg = getColoredPathway(pathway="WP554", graphId=c("ef1f3","e68e0"));
+#'   svg = getColoredPathway(pathway="WP554", graphId="ef1f3")
+#'   svg = getColoredPathway(pathway="WP554", graphId=c("ef1f3","e68e0"))
 #'   svg = getColoredPathway(pathway="WP554", graphId=c("ef1f3","e68e0"),
-#'                           color="00FF00");
+#'                           color="00FF00")
 #'   svg = getColoredPathway(pathway="WP554", graphId=c("ef1f3","e68e0"),
-#'                           color=c("FF0000", "0000FF"));
+#'                           color=c("FF0000", "0000FF"))
 #'   # writeLines(svg, "pathway.svg")
 #' }
 #' @importFrom caTools base64decode
 #' @export
 getColoredPathway <- function(pathway, revision=0,
                               graphId=NULL, color=NULL,
-                              fileType="svg") {
+                              fileType=c("svg","png","pdf")) {
+    fileType <- match.arg(fileType)
+
     if (is.null(color)&&!is.null(graphId)) {
         color = rep("FF0000", length(graphId))
     } else if (length(color) == 1) {

diff --git a/R/getCurationTags.R b/R/getCurationTags.R
@@ -3,7 +3,7 @@
 #'
 #' @description Retrieve information about curation tags for a specific pathway.
 #' @param pathway WikiPathways identifier (WPID) for the pathway to download, e.g. WP4
-#' @return List of tag name, display name, revision, text, timestampe and user
+#' @return A \code{list} of tag name, display name, revision, text, timestampe and user
 #' @examples {
 #' getCurationTags('WP554')
 #' }
@@ -18,7 +18,7 @@ getCurationTags <- function(pathway) {
 #'
 #' @description Retrieve names of curation tags for a specific pathway.
 #' @param pathway WikiPathways identifier (WPID) for the pathway to download, e.g. WP4
-#' @return List of tag names
+#' @return A \code{list} of tag names
 #' @examples {
 #' getCurationTagNames('WP554')
 #' }
@@ -31,8 +31,8 @@ getCurationTagNames <- function(pathway) {
 #' @title Get Every Instance of a Curation Tag
 #'
 #' @description Retrieve information about every instance of a given curation tag.
-#' @param tag Official name of curation tag, e.g., "Curation:FeaturedPathway"
-#' @return List of tag name, display name, revision, text, timestampe and user
+#' @param tag (\code{character}) Official name of curation tag, e.g., "Curation:FeaturedPathway"
+#' @return A \code{list} of tag name, display name, revision, text, timestampe and user
 #' @examples {
 #' getEveryCurationTag('Curation:FeaturedPathway')
 #' }
@@ -46,8 +46,8 @@ getEveryCurationTag <- function(tag) {
 #' @title Get Pathways by Curation Tag 
 #'
 #' @description Retrieve pathway information for every pathway with a given curation tag.
-#' @param tag Official name of curation tag, e.g., "Curation:FeaturedPathway"
-#' @return List of pathway information, including WPID, url, name, species and revision
+#' @param tag (\code{character}) Official name of curation tag, e.g., "Curation:FeaturedPathway"
+#' @return A \code{list} of pathway information, including WPID, url, name, species and revision
 #' @examples {
 #' getPathwaysByCurationTag('Curation:FeaturedPathway')
 #' }
@@ -61,8 +61,8 @@ getPathwaysByCurationTag <- function(tag) {
 #' @title Get Pathway WPIDs by Curation Tag 
 #'
 #' @description Retrieve pathway WPIDs for every pathway with a given curation tag.
-#' @param tag Official name of curation tag, e.g., "Curation:FeaturedPathway"
-#' @return List of pathway WPIDs
+#' @param tag (\code{character}) Official name of curation tag, e.g., "Curation:FeaturedPathway"
+#' @return A \code{list} of pathway WPIDs
 #' @examples {
 #' getPathwayIdsByCurationTag('Curation:FeaturedPathway')
 #' }

diff --git a/R/getOntologyTerms.R b/R/getOntologyTerms.R
@@ -3,7 +3,7 @@
 #'
 #' @description Retrieve information about ontology terms for a specific pathway.
 #' @param pathway WikiPathways identifier (WPID) for the pathway to download, e.g. WP4
-#' @return List of tag name, display name, revision, text, timestampe and user
+#' @return A \code{list} of tag name, display name, revision, text, timestampe and user
 #' @examples {
 #' getOntologyTerms('WP554')
 #' }
@@ -18,7 +18,7 @@ getOntologyTerms <- function(pathway) {
 #'
 #' @description Retrieve names of ontology terms for a specific pathway.
 #' @param pathway WikiPathways identifier (WPID) for the pathway to download, e.g. WP4
-#' @return List of term names
+#' @return A \code{list} of term names
 #' @examples {
 #' getOntologyTermNames('WP554')
 #' }
@@ -32,7 +32,7 @@ getOntologyTermNames <- function(pathway) {
 #'
 #' @description Retrieve identifiers of ontology terms for a specific pathway.
 #' @param pathway WikiPathways identifier (WPID) for the pathway to download, e.g. WP4
-#' @return List of term identifiers
+#' @return A \code{list} of term identifiers
 #' @examples {
 #' getOntologyTermIds('WP554')
 #' }
@@ -46,8 +46,8 @@ getOntologyTermIds <- function(pathway) {
 #' @title Get Pathways by Ontology Term 
 #'
 #' @description Retrieve pathway information for every pathway with a given ontology term.
-#' @param term Official name of ontology term, e.g., "PW:0000045"
-#' @return List of pathway information, including WPID, url, name, species and revision
+#' @param term (\code{character}) Official name of ontology term, e.g., "PW:0000045"
+#' @return A \code{list} of pathway information, including WPID, url, name, species and revision
 #' @examples {
 #' getPathwaysByOntologyTerm('PW:0000045')
 #' }
@@ -61,8 +61,8 @@ getPathwaysByOntologyTerm <- function(term) {
 #' @title Get Pathway WPIDs by Ontology Term 
 #'
 #' @description Retrieve pathway WPIDs for every pathway with a given ontology term.
-#' @param term Official name of ontology term, e.g., "PW:0000045"
-#' @return List of pathway WPIDs
+#' @param term (\code{character}) Official name of ontology term, e.g., "PW:0000045"
+#' @return A \code{list} of pathway WPIDs
 #' @examples {
 #' getPathwayIdsByOntologyTerm('PW:0000045')
 #' }
@@ -75,8 +75,8 @@ getPathwayIdsByOntologyTerm <- function(term) {
 #' @title Get Pathways by Parent Ontology Term 
 #'
 #' @description Retrieve pathway information for every pathway with a child term of given ontology term.
-#' @param term Official name of ontology term, e.g., "PW:0000045"
-#' @return List of pathway information, including WPID, url, name, species and revision
+#' @param term (\code{character}) Official name of ontology term, e.g., "PW:0000045"
+#' @return A \code{list} of pathway information, including WPID, url, name, species and revision
 #' @examples {
 #' getPathwaysByParentOntologyTerm('PW:0000045')
 #' }
@@ -90,8 +90,8 @@ getPathwaysByParentOntologyTerm <- function(term) {
 #' @title Get Pathway WPIDs by Parent Ontology Term 
 #'
 #' @description Retrieve pathway WPIDs for every pathway with a child term of given ontology term
-#' @param term Official name of ontology term, e.g., "PW:0000045"
-#' @return List of pathway WPIDs
+#' @param term (\code{character}) Official name of ontology term, e.g., "PW:0000045"
+#' @return A \code{list} of pathway WPIDs
 #' @examples {
 #' getPathwayIdsByParentOntologyTerm('PW:0000045')
 #' }

diff --git a/R/getPathway.R b/R/getPathway.R
@@ -3,7 +3,7 @@
 #'
 #' @description Retrieve a specific pathway in the GPML format
 #' @param pathway WikiPathways identifier (WPID) for the pathway to download, e.g. WP4
-#' @param revision (optional) Number to indicate a specific revision to download
+#' @param revision (\code{integer}, optional) Number to indicate a specific revision to download
 #' @return GPML
 #' @examples {
 #' getPathway('WP554')

diff --git a/R/getPathwayHistory.R b/R/getPathwayHistory.R
@@ -3,10 +3,10 @@
 #'
 #' @description Retrieve the revision history of a pathway.
 #' @param pathway WikiPathways identifier (WPID) for the pathway to download, e.g. WP4
-#' @param timestamp Limit by time, only history items after the given time, 
+#' @param timestamp (\code{integer}) Limit by time, only history items after the given time, 
 #' e.g., 20180201 for revisions since Feb 1st, 2018. Any length of timestamp is 
 #' accepted, upto 14 digits, e.g., 2018, 201802, 20180201063011, etc.
-#' @return List of revisions, including user and comment
+#' @return A \code{list} of revisions, including user and comment
 #' @examples {
 #' getPathwayHistory('WP554',20180201)
 #' }

diff --git a/R/getPathwayInfo.R b/R/getPathwayInfo.R
@@ -3,7 +3,7 @@
 #'
 #' @description Retrieve information for a specific pathway
 #' @param pathway WikiPathways identifier (WPID) for the pathway to download, e.g. WP4
-#' @return List of pathway WPID, URL, name, species and latest revision
+#' @return A \code{list} of pathway WPID, URL, name, species and latest revision
 #' @examples {
 #' getPathwayInfo('WP554')
 #' }