Adding roxygen documentation

ropensci-archive · Dec 10, 2011 · 4cfc1cf · 4cfc1cf
1 parent 6ed15d8
commit 4cfc1cf
Show file tree

Hide file tree

Showing 16 changed files with 255 additions and 165 deletions.
diff --git a/.gitignore b/.gitignore
@@ -0,0 +1 @@
+.DS_Store
diff --git a/DESCRIPTION b/DESCRIPTION
@@ -1,10 +1,39 @@
 Package: rplos
 Description: A programmatic interface to the
- Web Service methods provided by the Public Library
- of Science journals.  
+    Web Service methods provided by the Public Library
+    of Science journals.
 Title: Interface to PLoS Journals API methods
 Version: 0.0-1
 License: BSD
-Author: Scott Chamberlain, Carl Boettiger 
-Maintainer: Scott Chamberlain <myrmecocystus@gmail.com> 
-Imports: RJSONIO, RCurl (>= 1.6), stringr, ggplot2, data.table 
+Author: Scott Chamberlain, Carl Boettiger
+Maintainer: Scott Chamberlain <myrmecocystus@gmail.com>
+Imports:
+    RJSONIO,
+    RCurl (>= 1.6),
+    stringr,
+    ggplot2,
+    data.table
+Collate:
+    'almplosallviews.R'
+    'almplosallviewsdf.R'
+    'almplotallviews.R'
+    'almpub.R'
+    'almpubmedcentid.R'
+    'almpubmedid.R'
+    'almtitle.R'
+    'almtotcites.R'
+    'almupdated.R'
+    'articlelength.R'
+    'browsepaper.R'
+    'crossref.R'
+    'formatarticleurl.R'
+    'otherstuff.R'
+    'plosabstract.R'
+    'plosauthor.R'
+    'plosfigtabcaps.R'
+    'plossubject.R'
+    'plostitle.R'
+    'plosviews.R'
+    'plosword.R'
+    'plot_throughtime.R'
+    'searchplos.R'
diff --git a/NAMESPACE b/NAMESPACE
@@ -1,8 +1 @@
-import(RCurl)
-import(stringr)
-import(RJSONIO)
-import(ggplot2)
-import(data.table)
-import(googleVis)
-
-export(formatarticleurl, searchplos, plosauthor, plosword, plosabstract, plossubject, plostitle, crossref, plot_throughtime, articlelength)
+export(almplosallviews)
diff --git a/R/almplosallviews.R b/R/almplosallviews.R
@@ -1,24 +1,25 @@
-# plosallviews.R
-
-plosallviews <- 
-# Function htmlviews to summarise all pdf, html, and xml views
-# Args:
-#   doi: digital object identifier for an article in PLoS Journals  (string)
-#   source_ (character): Five categories of sources
-#     Usage stats: counter [PLoS' own stats], pmc [PubMed].
-#     Citations: pubmed, crossref, scopus, or wos [Web of Science].
-#     Social: citeulike.
-#     Blog entries: nature (no. of Nature blog articles that mentioned the article).
-#     Inactive sources: researchblogging, connotea, bloglines, postgenomic
-#   citations: include the individual citing document URIs, grouped by source,
-#     TRUE (T) or FALSE (F) (character)
-#   history: include a historical record of citation counts per month (cumulative), 
-#     grouped by source, TRUE (T) or FALSE (F) (character)
-#   downform: download format (json, xml or csv)
-# Examples: 
-#   plosallviews('10.1371/journal.pbio.0000012', 'counter', T, T, 'xml')
-#   plosallviews('10.1371/journal.pbio.0000012', 'citeulike', T, T, 'json')
-#   plosallviews('10.1371/journal.pone.0005723', 'counter', T, T, 'csv')
+#' almplosallviews.R   Alt-metrics_allviews
+#' @param doi digital object identifier for an article in PLoS Journals
+#' @param source_ source, one of counter, mpc, pubmed, crossref, scopus, wos, 
+#'    citeulike, nature, researchblogging, connotea, bloglines, postgenomic
+#' @param citations include the individual citing document URIs, grouped by 
+#'    source (logical)
+#' @param history include a historical record of citation counts per month 
+#'    (cumulative), grouped by source (logical)
+#' @param downform download format (json, xml or csv)
+#' @param key your PLoS API key, either enter, or loads from .Rprofile
+#' @param url the PLoS API url for the function (should be left to default)
+#' @param ... optional additional curl options (debugging tools mostly)
+#' @param curl If using in a loop, call getCurlHandle() first and pass 
+#'  the returned value in here (avoids unnecessary footprint)
+#' @return altmetrics as xml, json, or csv
+#' @examples \dontrun{
+#'  plosallviews('10.1371/journal.pbio.0000012', 'counter', T, T, 'xml')
+#'   plosallviews('10.1371/journal.pbio.0000012', 'citeulike', T, T, 'json')
+#'   plosallviews('10.1371/journal.pone.0005723', 'counter', T, T, 'csv')
+#' }
+#' @export
+almplosallviews <- 
 
 function(doi, source_ = NA, citations = FALSE, history = FALSE, downform = NA,
   url = 'http://alm.plos.org/articles',
@@ -53,6 +54,5 @@ function(doi, source_ = NA, citations = FALSE, history = FALSE, downform = NA,
 #       citations2, history2, '&api_key=', key, sep='')
 #     outprod <- read.csv(urlcsv)
 #   }
-
 return(outprod)
 }
diff --git a/R/almplotallviews.R b/R/almplotallviews.R
@@ -1,17 +1,16 @@
-# plotallviews.R
-
-plotallviews <- 
-# Args:
-#   data: JSON output downloaded from PLoS (character)
-#   type: plot views for html, pdf, xml, any combination of two (e.g., 'html,pdf'), 
-#     or all (character)
-# Examples
-#  out <- plosallviews('10.1371/journal.pbio.0000012', 'counter', 'json') 
-#  plotallviews(out, 'all')
-#  plotallviews(out, 'pdf')
-#  plotallviews(out, 'html,pdf')
-# Input: for now, the JSON output from the plosallviews function
-# Output: ggplot line plot
+#' almplotallviews.R   Alt-metrics_plot_allviews
+#' @param data JSON output downloaded from PLoS (character)
+#' @param type plot views for html, pdf, xml, any combination of two 
+#'     (e.g., 'html,pdf'), or all (character)
+#' @return ggplot line plot
+#' @examples \dontrun{
+#'    out <- plosallviews('10.1371/journal.pbio.0000012', 'counter', 'json') 
+#'    plotallviews(out, 'all')
+#'    plotallviews(out, 'pdf')
+#'    plotallviews(out, 'html,pdf')
+#' }
+#' @export
+almplotallviews <- 
 
 function(data, type = NA) {
 

diff --git a/R/almpub.R b/R/almpub.R
@@ -1,11 +1,16 @@
-# almpub.R
-
+#' almpub.R   Alt-metrics date updated
+#' @param doi digital object identifier for an article in PLoS Journals
+#' @param key your PLoS API key, either enter, or loads from .Rprofile
+#' @param url the PLoS API url for the function (should be left to default)
+#' @param ... optional additional curl options (debugging tools mostly)
+#' @param curl If using in a loop, call getCurlHandle() first and pass 
+#'  the returned value in here (avoids unnecessary footprint)
+#' @return date when article data was last updated
+#' @examples \dontrun{
+#'    almpub('10.1371/journal.pbio.0000012')
+#' }
+#' @export
 almpub <- 
-# Function retrieves date when article data was last updated
-# Args:
-#   doi: digital object identifier for an article in PLoS Journals  (string)
-# Examples: 
-#   almpub('10.1371/journal.pbio.0000012')
 
 function(doi,
   url = 'http://alm.plos.org/articles',
@@ -15,7 +20,5 @@ function(doi,
 
   url2 <- paste(url, "/", doi, '.json?api_key=', key, sep='')
   tt <- getURLContent(url2)
-  outprod <- fromJSON(I(tt))$article$published
-
-  return(outprod)
+  fromJSON(I(tt))$article$published
 }
diff --git a/R/almpubmedcentid.R b/R/almpubmedcentid.R
@@ -1,11 +1,17 @@
-# almpubmedcentid.R
+#' almpubmedcentid.R   Alt-metrics PubMed Central article ID
+#' @param doi digital object identifier for an article in PLoS Journals
+#' @param key your PLoS API key, either enter, or loads from .Rprofile
+#' @param url the PLoS API url for the function (should be left to default)
+#' @param ... optional additional curl options (debugging tools mostly)
+#' @param curl If using in a loop, call getCurlHandle() first and pass 
+#'  the returned value in here (avoids unnecessary footprint)
+#' @return retrieves the PubMed Central article ID
+#' @examples \dontrun{
+#'    almpubmedcentid('10.1371/journal.pbio.0000012')
+#' }
+#' @export
 
 almpubmedcentid <- 
-# Function retrieves the PubMed Central article ID
-# Args:
-#   doi: digital object identifier for an article in PLoS Journals  (string)
-# Examples: 
-#   almpubmedcentid('10.1371/journal.pbio.0000012')
 
 function(doi,
   url = 'http://alm.plos.org/articles',
@@ -15,7 +21,5 @@ function(doi,
 
   url2 <- paste(url, "/", doi, '.json?api_key=', key, sep='')
   tt <- getURLContent(url2)
-  outprod <- fromJSON(I(tt))$article$pub_med_central
-
-  return(outprod)
+  fromJSON(I(tt))$article$pub_med_central
 }
diff --git a/R/almpubmedid.R b/R/almpubmedid.R
@@ -1,11 +1,16 @@
-# almpubmedid.R
-
+#' almpubmedid.R   Alt-metrics PubMed article ID
+#' @param doi digital object identifier for an article in PLoS Journals
+#' @param key your PLoS API key, either enter, or loads from .Rprofile
+#' @param url the PLoS API url for the function (should be left to default)
+#' @param ... optional additional curl options (debugging tools mostly)
+#' @param curl If using in a loop, call getCurlHandle() first and pass 
+#'  the returned value in here (avoids unnecessary footprint)
+#' @return retrieves the PubMed article ID
+#' @examples \dontrun{
+#'    almpubmedid('10.1371/journal.pbio.0000012')
+#' }
+#' @export
 almpubmedid <- 
-# Function retrieves the PubMed article ID
-# Args:
-#   doi: digital object identifier for an article in PLoS Journals  (string)
-# Examples: 
-#   almpubmedid('10.1371/journal.pbio.0000012')
 
 function(doi,
   url = 'http://alm.plos.org/articles',
@@ -15,7 +20,5 @@ function(doi,
 
   url2 <- paste(url, "/", doi, '.json?api_key=', key, sep='')
   tt <- getURLContent(url2)
-  outprod <- fromJSON(I(tt))$article$pub_med
-
-  return(outprod)
+  fromJSON(I(tt))$article$pub_med
 }
diff --git a/R/almtitle.R b/R/almtitle.R
@@ -1,11 +1,16 @@
-# almtitle.R
-
+#' almtitle.R   Alt-metrics title of article
+#' @param doi digital object identifier for an article in PLoS Journals
+#' @param key your PLoS API key, either enter, or loads from .Rprofile
+#' @param url the PLoS API url for the function (should be left to default)
+#' @param ... optional additional curl options (debugging tools mostly)
+#' @param curl If using in a loop, call getCurlHandle() first and pass 
+#'  the returned value in here (avoids unnecessary footprint)
+#' @return title of article
+#' @examples \dontrun{
+#'    almtitle('10.1371/journal.pbio.0000012')
+#' }
+#' @export
 almtitle <- 
-# Function retrieves the PubMed Central article ID
-# Args:
-#   doi: digital object identifier for an article in PLoS Journals  (string)
-# Examples: 
-#   almtitle('10.1371/journal.pbio.0000012')
 
 function(doi,
   url = 'http://alm.plos.org/articles',
@@ -15,7 +20,5 @@ function(doi,
 
   url2 <- paste(url, "/", doi, '.json?api_key=', key, sep='')
   tt <- getURLContent(url2)
-  outprod <- fromJSON(I(tt))$article$title
-
-  return(outprod)
+  fromJSON(I(tt))$article$title
 }
diff --git a/R/almtotcites.R b/R/almtotcites.R
@@ -1,11 +1,16 @@
-# almtotcites.R
-
+#' almtotcites.R   Alt-metrics total citation points from all sources
+#' @param doi digital object identifier for an article in PLoS Journals
+#' @param key your PLoS API key, either enter, or loads from .Rprofile
+#' @param url the PLoS API url for the function (should be left to default)
+#' @param ... optional additional curl options (debugging tools mostly)
+#' @param curl If using in a loop, call getCurlHandle() first and pass 
+#'  the returned value in here (avoids unnecessary footprint)
+#' @return total no. data points recorded for this article from all sources
+#' @examples \dontrun{
+#'    almtotcites('10.1371/journal.pbio.0000012')
+#' }
+#' @export
 almtotcites <- 
-# Function retrieves the PubMed Central article ID
-# Args:
-#   doi: digital object identifier for an article in PLoS Journals  (string)
-# Examples: 
-#   almtotcites('10.1371/journal.pbio.0000012')
 
 function(doi,
   url = 'http://alm.plos.org/articles',
@@ -15,7 +20,5 @@ function(doi,
 
   url2 <- paste(url, "/", doi, '.json?api_key=', key, sep='')
   tt <- getURLContent(url2)
-  outprod <- fromJSON(I(tt))$article$citations_count
-
-  return(outprod)
+  fromJSON(I(tt))$article$citations_count
 }
diff --git a/R/almupdated.R b/R/almupdated.R
@@ -1,11 +1,16 @@
-# almupdated.R
-
+#' almupdated.R   Alt-metrics date when article data was last updated
+#' @param doi digital object identifier for an article in PLoS Journals
+#' @param key your PLoS API key, either enter, or loads from .Rprofile
+#' @param url the PLoS API url for the function (should be left to default)
+#' @param ... optional additional curl options (debugging tools mostly)
+#' @param curl If using in a loop, call getCurlHandle() first and pass 
+#'  the returned value in here (avoids unnecessary footprint)
+#' @return date when article data was last updated
+#' @examples \dontrun{
+#'    almupdated('10.1371/journal.pbio.0000012')
+#' }
+#' @export
 almupdated <- 
-# Function retrieves date when article data was last updated
-# Args:
-#   doi: digital object identifier for an article in PLoS Journals  (string)
-# Examples: 
-#   almupdated('10.1371/journal.pbio.0000012')
 
 function(doi,
   url = 'http://alm.plos.org/articles',
@@ -15,7 +20,5 @@ function(doi,
 
   url2 <- paste(url, "/", doi, '.json?api_key=', key, sep='')
   tt <- getURLContent(url2)
-  outprod <- fromJSON(I(tt))$article$updated_at
-
-  return(outprod)
+  fromJSON(I(tt))$article$updated_at
 }
diff --git a/R/articlelength.R b/R/articlelength.R
@@ -1,18 +1,24 @@
-# Retrieve article length
-
+#' articlelength.R   Get article length
+#' @param id article identifier DOI = id, or subject area, e.g.: 'ecology'
+#' @param fields fields to return from search (character) [e.g., 'id,title'], 
+#'     any combination of search fields [see plosfields$field]
+#' @param limit number of results to return (integer)
+#' @param searchin search field to search in (character)
+#' @param url the PLoS API url for the function (should be left to default)
+#' @param key your PLoS API key, either enter, or loads from .Rprofile
+#' @param ... optional additional curl options (debugging tools mostly)
+#' @param curl If using in a loop, call getCurlHandle() first and pass 
+#'  the returned value in here (avoids unnecessary footprint)
+#' @return length of articles (no. words)
+#' @examples \dontrun{
+#'  articlelength("10.1371/journal.pone.0004045", "body")
+#'  articlelength("10.1371/journal.pone.0004045", "everything")
+#'  articlelength("10.1371/journal.pone.0004045", "title")
+#'  articlelength("ecology", "materials_and_methods", 500, "subject")
+#'  articlelength("ecology", "results_and_discussion", 500, "subject")
+#' }
+#' @export
 articlelength <- 
-# Args:
-#   id: article identifier DOI = id, or subject area, e.g.: 'ecology' (character)
-#   fields: fields to return from search (character) [e.g., 'id,title'], 
-#     any combination of search fields [see plosfields$field]
-#   limit: number of results to return (integer)
-#   searchin: search field to search in (character)
-# Examples:
-#   articlelength("10.1371/journal.pone.0004045", "body")
-#   articlelength("10.1371/journal.pone.0004045", "everything")
-#   articlelength("10.1371/journal.pone.0004045", "title")
-#   articlelength("ecology", "materials_and_methods", 500, "subject")
-#   articlelength("ecology", "results_and_discussion", 500, "subject")
 
 function(id = NA, fields = NA, limit = NA, searchin = NA,
   url = 'http://api.plos.org/search',