docker/config.yml
doc/.site
doc/sdk/python/arvados
+doc/sdk/R/arvados
sdk/perl/MYMETA.*
sdk/perl/Makefile
sdk/perl/blib
R -q -e "library('testthat')" || fatal "No testthat. Try: apt-get install r-cran-testthat"
# needed for roxygen2, needed for devtools, needed for R sdk
pkg-config --exists libxml-2.0 || fatal "No libxml2. Try: apt-get install libxml2-dev"
+ # needed for pkgdown, builds R SDK doc pages
+ which pandoc || fatal "No pandoc. Try: apt-get install pandoc"
}
rotate_logfile() {
if (!requireNamespace("roxygen2")) {
install.packages("roxygen2")
}
+if (!requireNamespace("pkgdown")) {
+ devtools::install_github("hadley/pkgdown")
+}
devtools::install_dev_deps()
EOF
}
require "rubygems"
require "colorize"
-task :generate => [ :realclean, 'sdk/python/arvados/index.html' ] do
+task :generate => [ :realclean, 'sdk/python/arvados/index.html', 'sdk/R/arvados/index.html' ] do
vars = ['baseurl', 'arvados_api_host', 'arvados_workbench_host']
vars.each do |v|
if ENV[v]
end
end
+file "sdk/R/arvados/index.html" do |t|
+ `which R`
+ if $? == 0
+ Dir.chdir("../sdk/R/") do
+ STDERR.puts `R --quiet --vanilla -e 'pkgdown::build_site()' 2>&1`
+ end
+ raise if $? != 0
+ cp_r("../sdk/R/docs", "sdk/R/arvados")
+ else
+ puts "Warning: R not found, R documentation will not be generated".colorize(:light_red)
+ end
+end
+
task :linkchecker => [ :generate ] do
Dir.chdir(".site") do
`which linkchecker`
task :clean do
rm_rf "sdk/python/arvados"
+ rm_rf "sdk/R/arvados"
+ rm_rf "../sdk/R/docs"
end
require "zenweb/tasks"
- Go:
- sdk/go/index.html.textile.liquid
- sdk/go/example.html.textile.liquid
+ - R:
+ - sdk/R/R.html.textile.liquid
- Perl:
- sdk/perl/index.html.textile.liquid
- sdk/perl/example.html.textile.liquid
--- /dev/null
+---
+layout: default
+navsection: sdk
+navmenu: R
+title: "R Reference"
+
+no_nav_left: true
+...
+{% comment %}
+Copyright (C) The Arvados Authors. All rights reserved.
+
+SPDX-License-Identifier: CC-BY-SA-3.0
+{% endcomment %}
+
+notextile. <iframe src="arvados/" style="width:100%; height:100%; border:none" />
* "Python SDK":{{site.baseurl}}/sdk/python/sdk-python.html
* "Command line SDK":{{site.baseurl}}/sdk/cli/install.html ("arv")
* "Go SDK":{{site.baseurl}}/sdk/go/index.html
+* "R SDK":{{site.baseurl}}/sdk/go/index.html
* "Perl SDK":{{site.baseurl}}/sdk/perl/index.html
* "Ruby SDK":{{site.baseurl}}/sdk/ruby/index.html
* "Java SDK":{{site.baseurl}}/sdk/java/index.html
^.*\.Rproj$
^\.Rproj\.user$
+^docs$
+^pkgdown$
Type: Package
Title: Arvados R SDK
Version: 0.0.2
-Author: Fuad Muhic
+Authors@R: person("Fuad", "Muhic", role = c("aut", "cre"), email = "fmuhic@capeannenterprises.com")
Maintainer: Ward Vandewege <wvandewege@veritasgenetics.com>
Description: This is the Arvados R SDK
URL: http://doc.arvados.org
# Generated by roxygen2: do not edit by hand
+S3method(print,Arvados)
+S3method(print,ArvadosFile)
+S3method(print,Collection)
+S3method(print,Subcollection)
export(Arvados)
export(ArvadosFile)
export(Collection)
export(Subcollection)
-export(print.Arvados)
-export(print.ArvadosFile)
-export(print.Collection)
-export(print.Subcollection)
source("./R/HttpRequest.R")
source("./R/HttpParser.R")
-#' Arvados SDK Object
+#' Arvados
+#'
+#' Arvados class gives users ability to manipulate collections and projects.
+#'
+#' @section Usage:
+#' \preformatted{arv = Arvados$new(authToken = NULL, hostName = NULL, numRetries = 0)}
#'
-#' All Arvados logic is inside this class
+#' @section Arguments:
+#' \describe{
+#' \item{authToken}{Authentification token. If not specified ARVADOS_API_TOKEN environment variable will be used.}
+#' \item{hostName}{Host name. If not specified ARVADOS_API_HOST environment variable will be used.}
+#' \item{numRetries}{Number which specifies how many times to retry failed service requests.}
+#' }
+#'
+#' @section Methods:
+#' \describe{
+#' \item{getToken()}{Returns authentification token currently in use.}
+#' \item{getHostName()}{Returns host name currently in use.}
+#' \item{getNumRetries()}{Returns number which specifies how many times to retry failed service requests.}
+#' \item{setNumRetries(newNumOfRetries)}{Sets number which specifies how many times to retry failed service requests.}
+#' \item{getCollection(uuid)}{Get collection with specified UUID.}
+#' \item{listCollections(filters = NULL, limit = 100, offset = 0)}{Returns list of collections based on filters parameter.}
+#' \item{listAllCollections(filters = NULL)}{Lists all collections, based on filters parameter, even if the number of items is greater than maximum API limit.}
+#' \item{deleteCollection(uuid)}{Deletes collection with specified UUID.}
+#' \item{updateCollection(uuid, newContent)}{Updates collection with specified UUID.}
+#' \item{createCollection(content)}{Creates new collection.}
+#' \item{getProject(uuid)}{Get project with specified UUID.}
+#' \item{listProjects(filters = NULL, limit = 100, offset = 0)}{Returns list of projects based on filters parameter.}
+#' \item{listAllProjects(filters = NULL)}{Lists all projects, based on filters parameter, even if the number of items is greater than maximum API limit.}
+#' \item{deleteProject(uuid)}{Deletes project with specified UUID.}
+#' \item{updateProject(uuid, newContent)}{Updates project with specified UUID.}
+#' \item{createProject(content)}{Creates new project.}
+#' }
#'
-#' @field token Token represents user authentification token.
-#' @field host Host represents server name we wish to connect to.
-#' @examples arv = Arvados$new("token", "host_name")
-#' @export Arvados
+#' @name Arvados
+#' @examples
+#' \dontrun{
+#' arv <- Arvados$new("your Arvados token", "example.arvadosapi.com")
+#'
+#' collection <- arv$getCollection("uuid")
+#'
+#' collectionList <- arv$listCollections(list(list("name", "like", "Test%")))
+#' collectionList <- arv$listAllCollections(list(list("name", "like", "Test%")))
+#'
+#' deletedCollection <- arv$deleteCollection("uuid")
+#'
+#' updatedCollection <- arv$updateCollection("uuid", list(name = "New name",
+#' description = "New description"))
+#'
+#' createdCollection <- arv$createCollection(list(name = "Example",
+#' description = "This is a test collection"))
+#' }
+NULL
+
+#' @export
Arvados <- R6::R6Class(
"Arvados",
cloneable = FALSE
)
-#' @export print.Arvados
-print.Arvados = function(arvados)
+#' print.Arvados
+#'
+#' Custom print function for Arvados class
+#'
+#' @param x Instance of Arvados class
+#' @param ... Optional arguments.
+#' @export
+print.Arvados = function(x, ...)
{
- cat(paste0("Type: ", "\"", "Arvados", "\""), sep = "\n")
- cat(paste0("Host: ", "\"", arvados$getHostName(), "\""), sep = "\n")
- cat(paste0("Token: ", "\"", arvados$getToken(), "\""), sep = "\n")
+ cat(paste0("Type: ", "\"", "Arvados", "\""), sep = "\n")
+ cat(paste0("Host: ", "\"", x$getHostName(), "\""), sep = "\n")
+ cat(paste0("Token: ", "\"", x$getToken(), "\""), sep = "\n")
}
source("./R/util.R")
-#' ArvadosFile Object
+#' ArvadosFile
+#'
+#' ArvadosFile class represents a file inside Arvados collection.
+#'
+#' @section Usage:
+#' \preformatted{file = ArvadosFile$new(name)}
#'
-#' Update description
+#' @section Arguments:
+#' \describe{
+#' \item{name}{Name of the file.}
+#' }
+#'
+#' @section Methods:
+#' \describe{
+#' \item{getName()}{Returns name of the file.}
+#' \item{getRelativePath()}{Returns file path relative to the root.}
+#' \item{read(contentType = "raw", offset = 0, length = 0)}{Read file content.}
+#' \item{write(content, contentType = "text/html")}{Write to file (override current content of the file).}
+#' \item{connection(rw)}{Get connection opened in "read" or "write" mode.}
+#' \item{flush()}{Write connections content to a file (override current content of the file).}
+#' \item{remove(name)}{Removes ArvadosFile or Subcollection specified by name from the subcollection.}
+#' \item{getSizeInBytes()}{Returns file size in bytes.}
+#' \item{move(newLocation)}{Moves file to a new location inside collection.}
+#' }
#'
-#' @export ArvadosFile
+#' @name ArvadosFile
+#' @examples
+#' \dontrun{
+#' myFile <- ArvadosFile$new("myFile")
+#'
+#' myFile$write("This is new file content")
+#' fileContent <- myFile$read()
+#' fileContent <- myFile$read("text")
+#' fileContent <- myFile$read("raw", offset = 8, length = 4)
+#'
+#' #Write a table:
+#' arvConnection <- myFile$connection("w")
+#' write.table(mytable, arvConnection)
+#' arvadosFile$flush()
+#'
+#' #Read a table:
+#' arvConnection <- myFile$connection("r")
+#' mytable <- read.table(arvConnection)
+#'
+#' myFile$move("newFolder/myFile")
+#' }
+NULL
+
+#' @export
ArvadosFile <- R6::R6Class(
"ArvadosFile",
cloneable = FALSE
)
-#' @export print.ArvadosFile
-print.ArvadosFile = function(arvadosFile)
+#' print.ArvadosFile
+#'
+#' Custom print function for ArvadosFile class
+#'
+#' @param x Instance of ArvadosFile class
+#' @param ... Optional arguments.
+#' @export
+print.ArvadosFile = function(x, ...)
{
collection <- NULL
- relativePath <- arvadosFile$getRelativePath()
+ relativePath <- x$getRelativePath()
- if(!is.null(arvadosFile$getCollection()))
+ if(!is.null(x$getCollection()))
{
- collection <- arvadosFile$getCollection()$uuid
+ collection <- x$getCollection()$uuid
relativePath <- paste0("/", relativePath)
}
cat(paste0("Type: ", "\"", "ArvadosFile", "\""), sep = "\n")
- cat(paste0("Name: ", "\"", arvadosFile$getName(), "\""), sep = "\n")
+ cat(paste0("Name: ", "\"", x$getName(), "\""), sep = "\n")
cat(paste0("Relative path: ", "\"", relativePath, "\""), sep = "\n")
cat(paste0("Collection: ", "\"", collection, "\""), sep = "\n")
}
source("./R/RESTService.R")
source("./R/util.R")
-#' Arvados Collection Object
+#' Collection
+#'
+#' Collection class provides interface for working with Arvados collections.
+#'
+#' @section Usage:
+#' \preformatted{collection = Collection$new(arv, uuid)}
#'
-#' Update description
+#' @section Arguments:
+#' \describe{
+#' \item{arv}{Arvados object.}
+#' \item{uuid}{UUID of a collection.}
+#' }
+#'
+#' @section Methods:
+#' \describe{
+#' \item{add(content)}{Adds ArvadosFile or Subcollection specified by content to the collection.}
+#' \item{create(fileNames, relativePath = "")}{Creates one or more ArvadosFiles and adds them to the collection at specified path.}
+#' \item{remove(fileNames)}{Remove one or more files from the collection.}
+#' \item{move(content, newLocation)}{Moves ArvadosFile or Subcollection to another location in the collection.}
+#' \item{getFileListing()}{Returns collections file content as character vector.}
+#' \item{get(relativePath)}{If relativePath is valid, returns ArvadosFile or Subcollection specified by relativePath, else returns NULL.}
+#' }
#'
-#' @examples arv = Collection$new(api, uuid)
-#' @export Collection
+#' @name Collection
+#' @examples
+#' \dontrun{
+#' arv <- Arvados$new("your Arvados token", "example.arvadosapi.com")
+#' collection <- Collection$new(arv, "uuid")
+#'
+#' newFile <- ArvadosFile$new("myFile")
+#' collection$add(newFile, "myFolder")
+#'
+#' createdFiles <- collection$create(c("main.cpp", lib.dll), "cpp/src/")
+#'
+#' collection$remove("location/to/my/file.cpp")
+#'
+#' collection$move("folder/file.cpp", "file.cpp")
+#'
+#' arvadosFile <- collection$get("location/to/my/file.cpp")
+#' arvadosSubcollection <- collection$get("location/to/my/directory/")
+#' }
+NULL
+
+#' @export
Collection <- R6::R6Class(
"Collection",
cloneable = FALSE
)
-#' @export print.Collection
-print.Collection = function(collection)
+#' print.Collection
+#'
+#' Custom print function for Collection class
+#'
+#' @param x Instance of Collection class
+#' @param ... Optional arguments.
+#' @export
+print.Collection = function(x, ...)
{
cat(paste0("Type: ", "\"", "Arvados Collection", "\""), sep = "\n")
- cat(paste0("uuid: ", "\"", collection$uuid, "\""), sep = "\n")
+ cat(paste0("uuid: ", "\"", x$uuid, "\""), sep = "\n")
}
source("./R/ArvadosFile.R")
source("./R/util.R")
-#' Arvados Collection Object
-#'
-#' Update description
-#'
-#' @examples arv = Collection$new(api, uuid)
CollectionTree <- R6::R6Class(
"CollectionTree",
public = list(
-#' HttpParser
-#'
HttpParser <- R6::R6Class(
"HttrParser",
source("./R/util.R")
-#' Arvados SubCollection Object
+#' Subcollection
+#'
+#' Subcollection class represents a folder inside Arvados collection.
+#' It is essentially a composite of ArvadosFiles and other Subcollections.
+#'
+#' @section Usage:
+#' \preformatted{subcollection = Subcollection$new(name)}
#'
-#' Update description
+#' @section Arguments:
+#' \describe{
+#' \item{name}{Name of the subcollection.}
+#' }
+#'
+#' @section Methods:
+#' \describe{
+#' \item{getName()}{Returns name of the subcollection.}
+#' \item{getRelativePath()}{Returns subcollection path relative to the root.}
+#' \item{add(content)}{Adds ArvadosFile or Subcollection specified by content to the subcollection.}
+#' \item{remove(name)}{Removes ArvadosFile or Subcollection specified by name from the subcollection.}
+#' \item{get(relativePath)}{If relativePath is valid, returns ArvadosFile or Subcollection specified by relativePath, else returns NULL.}
+#' \item{getFileListing()}{Returns subcollections file content as character vector.}
+#' \item{getSizeInBytes()}{Returns subcollections content size in bytes.}
+#' \item{move(newLocation)}{Moves subcollection to a new location inside collection.}
+#' }
#'
-#' @export Subcollection
+#' @name Subcollection
+#' @examples
+#' \dontrun{
+#' myFolder <- Subcollection$new("myFolder")
+#' myFile <- ArvadosFile$new("myFile")
+#'
+#' myFolder$add(myFile)
+#' myFolder$get("myFile")
+#' myFolder$remove("myFile")
+#'
+#' myFolder$move("newLocation/myFolder")
+#' }
+NULL
+
+#' @export
Subcollection <- R6::R6Class(
"Subcollection",
cloneable = FALSE
)
-#' @export print.Subcollection
-print.Subcollection = function(subCollection)
+#' print.Subcollection
+#'
+#' Custom print function for Subcollection class
+#'
+#' @param x Instance of Subcollection class
+#' @param ... Optional arguments.
+#' @export
+print.Subcollection = function(x, ...)
{
collection <- NULL
- relativePath <- subCollection$getRelativePath()
+ relativePath <- x$getRelativePath()
- if(!is.null(subCollection$getCollection()))
+ if(!is.null(x$getCollection()))
{
- collection <- subCollection$getCollection()$uuid
+ collection <- x$getCollection()$uuid
- if(!subCollection$getName() == "")
+ if(!x$getName() == "")
relativePath <- paste0("/", relativePath)
}
cat(paste0("Type: ", "\"", "Arvados Subcollection", "\""), sep = "\n")
- cat(paste0("Name: ", "\"", subCollection$getName(), "\""), sep = "\n")
+ cat(paste0("Name: ", "\"", x$getName(), "\""), sep = "\n")
cat(paste0("Relative path: ", "\"", relativePath, "\""), sep = "\n")
cat(paste0("Collection: ", "\"", collection, "\""), sep = "\n")
}
+++ /dev/null
-R SDK for Arvados
-
-This SDK focuses on providing support for accessing Arvados projects, collections, and the files within collections.
-
-The API is not final and feedback is solicited from users on ways in which it could be improved.
-
-INSTALLATION
-
-1. Install the dependencies
-
- > install.packages(c('R6', 'httr', 'stringr', 'jsonlite', 'curl', 'XML'))
-
-If needed, you may have to install the supporting packages first. On Linux, these are:
-
- libxml2-dev, libssl-dev, libcurl4-gnutls-dev or libcurl4-openssl-dev
-
-2. Install the ArvardosR package
-
- > install.packages('/path/to/ArvadosR_0.0.2.tar.gz', repos = NULL, type="source", dependencies = TRUE)
-
-
-EXAMPLES OF USAGE
-
-
-#Load Library and Initialize API:
-
-library('ArvadosR')
-arv <- Arvados$new() # uses environment variables ARVADOS_API_TOKEN and ARVADOS_API_HOST
-arv <- Arvados$new("your Arvados token", "example.arvadosapi.com")
-
-
-#Optionally, add numRetries parameter to specify number of times to retry failed service requests.
-#Default is 0.
-
-arv <- Arvados$new("your Arvados token", "example.arvadosapi.com", numRetries = 3)
-
-#This parameter can be set at any time using setNumRetries
-
-arv$setNumRetries(5)
-
---------------------------------------------------------------------------------------------------------------------------------
-
-#Get a collection:
-
-arv$getCollection("uuid")
-
---------------------------------------------------------------------------------------------------------------------------------
-
-#List collections:
-collectionList <- arv$listCollections(list(list("name", "like", "Test%"))) # offset of 0 and default limit of 100
-collectionList <- arv$listCollections(list(list("name", "like", "Test%")), limit = 10, offset = 2)
-
-collectionList$items_available # count of total number of items (may be more than returned due to paging)
-collectionList$items # items which match the filter criteria
-
-#Next example will list all collections even when the number of items is greater than maximum API limit
-
-collectionList <- arv$listAllCollections(list(list("name", "like", "Test%")))
-
---------------------------------------------------------------------------------------------------------------------------------
-
-#Delete a collection:
-
-deletedCollection <- arv$deleteCollection("uuid")
-
---------------------------------------------------------------------------------------------------------------------------------
-
-#Update a collection's metadata:
-
-updatedCollection <- arv$updateCollection("uuid", list(name = "New name", description = "New description"))
-
---------------------------------------------------------------------------------------------------------------------------------
-
-#Create collection:
-
-createdCollection <- arv$createCollection(list(name = "Example", description = "This is a test collection"))
-
-
---------------------------------------------------------------------------------------------------------------------------------
-COLLECTION CONTENT MANIPULATION
---------------------------------------------------------------------------------------------------------------------------------
-
-#Create collection object:
-
-collection <- Collection$new(arv, "uuid")
-
---------------------------------------------------------------------------------------------------------------------------------
-
-#Get list of files
-
-collection$getFileListing()
-
---------------------------------------------------------------------------------------------------------------------------------
-
-#This will return ArvadosFile or Subcollection from internal tree-like structure.
-
-arvadosFile <- collection$get("location/to/my/file.cpp")
-
-#or
-
-arvadosSubcollection <- collection$get("location/to/my/directory/")
-
---------------------------------------------------------------------------------------------------------------------------------
-
-#Read a table
-
-arvadosFile <- collection$get("myinput.txt")
-arvConnection <- arvadosFile$connection("r")
-mytable <- read.table(arvConnection)
-
-#Write a table
-
-arvadosFile <- collection$create("myoutput.txt")
-arvConnection <- arvadosFile$connection("w")
-write.table(mytable, arvConnection)
-arvadosFile$flush()
-
---------------------------------------------------------------------------------------------------------------------------------
-
-#Read whole file or just a portion of it.
-
-fileContent <- arvadosFile$read()
-fileContent <- arvadosFile$read("text")
-fileContent <- arvadosFile$read("raw", offset = 1024, length = 512)
-
---------------------------------------------------------------------------------------------------------------------------------
-
-#Get ArvadosFile or Subcollection size
-
-size <- arvadosFile$getSizeInBytes()
-size <- arvadosSubcollection$getSizeInBytes()
-
---------------------------------------------------------------------------------------------------------------------------------
-
-#Create new file in a collection
-
-collection$create(fileNames, optionalRelativePath)
-
-#Example
-
-mainFile <- collection$create("main.cpp", "cpp/src/")
-fileList <- collection$create(c("main.cpp", lib.dll), "cpp/src/")
-
---------------------------------------------------------------------------------------------------------------------------------
-
-#Add existing ArvadosFile or Subcollection to a collection
-
-folder <- Subcollection$new("src")
-file <- ArvadosFile$new("main.cpp")
-folder$add(file)
-
-collection$add(folder, "cpp")
-
-#This examples will add file "main.cpp" in "./cpp/src/" folder if folder exists.
-#If subcollection contains more files or folders they will be added recursively.
-
---------------------------------------------------------------------------------------------------------------------------------
-
-#Write to existing file (Override current content of the file)
-
-arvadosFile <- collection$get("location/to/my/file.cpp")
-
-arvadosFile$write("This is new file content")
-
---------------------------------------------------------------------------------------------------------------------------------
-
-#Delete file from a collection
-
-collection$remove("location/to/my/file.cpp")
-
-#You can remove both Subcollection and ArvadosFile
-#If subcollection contains more files or folders they will be removed recursively.
-
-#You can also remove multiple files
-
-collection$remove(c("path/to/my/file.cpp", "path/to/other/file.cpp"))
-
-#Delete file or folder from a Subcollection
-
-subcollection <- collection$get("mySubcollection/")
-subcollection$remove("fileInsideSubcollection.exe")
-subcollection$remove("folderInsideSubcollection/")
-
---------------------------------------------------------------------------------------------------------------------------------
-
-#Move file or folder inside collection
-
-#Directley from collection
-
-collection$move("folder/file.cpp", "file.cpp")
-
-#Or from file
-
-file <- collection$get("location/to/my/file.cpp")
-file$move("newDestination/file.cpp")
-
-#Or from subcollection
-
-subcollection <- collection$get("location/to/folder")
-subcollection$move("newDestination/folder")
-
-#Make sure to include new file name in destination
-#In second example file$move("newDestination/") will not work
-
---------------------------------------------------------------------------------------------------------------------------------
-WORKING WITH ARVADOS PROJECTS
---------------------------------------------------------------------------------------------------------------------------------
-
-#Get a project:
-
-arv$getProject("uuid")
-
---------------------------------------------------------------------------------------------------------------------------------
-
-#List projects:
-
-projects <- arv$listProjects(list(list("owner_uuid", "=", "aaaaa-j7d0g-ccccccccccccccc"))) # list subprojects of a project
-arv$listProjects(list(list("name","like","Example%"))) # list projects which have names beginning with Example
-
-#Next example will list all projects even when the number of items is greater than maximum API limit
-
-collectionList <- arv$listAllProjects(list(list("name","like","Example%")))
-
---------------------------------------------------------------------------------------------------------------------------------
-
-#Delete a project:
-
-deletedProject <- arv$deleteProject("uuid")
-
---------------------------------------------------------------------------------------------------------------------------------
-
-#Update project:
-
-updatedProject <- arv$updateProject("uuid", list(name = "new_name", description = "new description"))
-
---------------------------------------------------------------------------------------------------------------------------------
-
-#Create project:
-
-createdProject <- arv$createProject(list(name = "project_name", description = "project description"))
-
-
---------------------------------------------------------------------------------------------------------------------------------
-BUILDING THE ARVADOS SDK TARBALL
---------------------------------------------------------------------------------------------------------------------------------
-
-
-cd arvados/sdk
-R CMD build R
-
-This will create a tarball of the Arvados package in the current directory.
--- /dev/null
+## R SDK for Arvados
+
+This SDK focuses on providing support for accessing Arvados projects, collections, and the files within collections.
+The API is not final and feedback is solicited from users on ways in which it could be improved.
+
+### Installation
+
+```install.packages("ArvadosR", repos=c("http://r.arvados.org", getOption("repos")["CRAN"]), dependencies=TRUE)```
+
+Note: on Linux, you may have to install supporting packages.
+
+On Centos 7, this is:
+
+```yum install libxml2-devel openssl-devel curl-devel```
+
+On Debian, this is:
+
+```apt-get install build-essential libxml2-dev libssl-dev libcurl4-gnutls-dev```
+
+
+### Usage
+
+#### Initializing API
+
+```{r include=FALSE}
+knitr::opts_chunk$set(eval = FALSE)
+```
+
+* Load Library and Initialize API:
+
+ ```{r}
+ library('ArvadosR')
+ # use environment variables ARVADOS_API_TOKEN and ARVADOS_API_HOST
+ arv <- Arvados$new()
+
+ # provide them explicitly
+ arv <- Arvados$new("your Arvados token", "example.arvadosapi.com")
+ ```
+
+ Optionally, add numRetries parameter to specify number of times to retry failed service requests.
+ Default is 0.
+
+ ```{r}
+ arv <- Arvados$new("your Arvados token", "example.arvadosapi.com", numRetries = 3)
+ ```
+
+ This parameter can be set at any time using setNumRetries
+
+ ```{r}
+ arv$setNumRetries(5)
+ ```
+
+
+#### Working with collections
+
+* Get a collection:
+
+ ```{r}
+ collection <- arv$getCollection("uuid")
+ ```
+
+* List collections:
+
+ ```{r}
+ # offset of 0 and default limit of 100
+ collectionList <- arv$listCollections(list(list("name", "like", "Test%")))
+
+ collectionList <- arv$listCollections(list(list("name", "like", "Test%")), limit = 10, offset = 2)
+ ```
+
+ ```{r}
+ # count of total number of items (may be more than returned due to paging)
+ collectionList$items_available
+
+ # items which match the filter criteria
+ collectionList$items
+ ```
+
+* List all collections even if the number of items is greater than maximum API limit:
+
+ ```{r}
+ collectionList <- arv$listAllCollections(list(list("name", "like", "Test%")))
+ ```
+
+* Delete a collection:
+
+ ```{r}
+ deletedCollection <- arv$deleteCollection("uuid")
+ ```
+
+* Update a collection's metadata:
+
+ ```{r}
+ updatedCollection <- arv$updateCollection("uuid", list(name = "New name", description = "New description"))
+ ```
+
+* Create collection:
+
+ ```{r}
+ createdCollection <- arv$createCollection(list(name = "Example", description = "This is a test collection"))
+ ```
+
+
+#### Manipulating collection content
+
+* Create collection object:
+
+ ```{r}
+ collection <- Collection$new(arv, "uuid")
+ ```
+
+* Get list of files:
+
+ ```{r}
+ files <- collection$getFileListing()
+ ```
+
+* Get ArvadosFile or Subcollection from internal tree-like structure:
+
+ ```{r}
+ arvadosFile <- collection$get("location/to/my/file.cpp")
+ ```
+
+ or
+
+ ```{r}
+ arvadosSubcollection <- collection$get("location/to/my/directory/")
+ ```
+
+* Read a table:
+
+ ```{r}
+ arvadosFile <- collection$get("myinput.txt")
+ arvConnection <- arvadosFile$connection("r")
+ mytable <- read.table(arvConnection)
+ ```
+
+* Write a table:
+
+ ```{r}
+ arvadosFile <- collection$create("myoutput.txt")
+ arvConnection <- arvadosFile$connection("w")
+ write.table(mytable, arvConnection)
+ arvadosFile$flush()
+ ```
+
+* Write to existing file (override current content of the file):
+
+ ```{r}
+ arvadosFile <- collection$get("location/to/my/file.cpp")
+ arvadosFile$write("This is new file content")
+ ```
+
+* Read whole file or just a portion of it:
+
+ ```{r}
+ fileContent <- arvadosFile$read()
+ fileContent <- arvadosFile$read("text")
+ fileContent <- arvadosFile$read("raw", offset = 1024, length = 512)
+ ```
+
+* Get ArvadosFile or Subcollection size:
+
+ ```{r}
+ size <- arvadosFile$getSizeInBytes()
+ ```
+
+ or
+
+ ```{r}
+ size <- arvadosSubcollection$getSizeInBytes()
+ ```
+
+* Create new file in a collection:
+
+ ```{r}
+ collection$create(fileNames, optionalRelativePath)
+ ```
+
+ Example:
+
+ ```{r}
+ mainFile <- collection$create("main.cpp", "cpp/src/")
+ fileList <- collection$create(c("main.cpp", lib.dll), "cpp/src/")
+ ```
+
+* Add existing ArvadosFile or Subcollection to a collection:
+
+ ```{r}
+ folder <- Subcollection$new("src")
+ file <- ArvadosFile$new("main.cpp")
+ folder$add(file)
+ ```
+
+ ```{r}
+ collection$add(folder, "cpp")
+ ```
+
+ This examples will add file "main.cpp" in "./cpp/src/" folder if folder exists.
+ If subcollection contains more files or folders they will be added recursively.
+
+* Delete file from a collection:
+
+ ```{r}
+ collection$remove("location/to/my/file.cpp")
+ ```
+
+ You can remove both Subcollection and ArvadosFile.
+ If subcollection contains more files or folders they will be removed recursively.
+
+ You can also remove multiple files at once:
+
+ ```{r}
+ collection$remove(c("path/to/my/file.cpp", "path/to/other/file.cpp"))
+ ```
+
+* Delete file or folder from a Subcollection:
+
+ ```{r}
+ subcollection <- collection$get("mySubcollection/")
+ subcollection$remove("fileInsideSubcollection.exe")
+ subcollection$remove("folderInsideSubcollection/")
+ ```
+
+* Move file or folder inside collection:
+
+ Directley from collection
+
+ ```{r}
+ collection$move("folder/file.cpp", "file.cpp")
+ ```
+
+ Or from file
+
+ ```{r}
+ file <- collection$get("location/to/my/file.cpp")
+ file$move("newDestination/file.cpp")
+ ```
+
+ Or from subcollection
+
+ ```{r}
+ subcollection <- collection$get("location/to/folder")
+ subcollection$move("newDestination/folder")
+ ```
+
+ Make sure to include new file name in destination.
+ In second example file$move("newDestination/") will not work.
+
+#### Working with Aravdos projects
+
+* Get a project:
+
+ ```{r}
+ project <- arv$getProject("uuid")
+ ```
+
+* List projects:
+
+ ```{r}
+ # list subprojects of a project
+ projects <- arv$listProjects(list(list("owner_uuid", "=", "aaaaa-j7d0g-ccccccccccccccc")))
+
+ # list projects which have names beginning with Example
+ arv$listProjects(list(list("name","like","Example%")))
+ ```
+
+* List all projects even if the number of items is greater than maximum API limit:
+
+ ```{r}
+ collectionList <- arv$listAllProjects(list(list("name","like","Example%")))
+ ```
+
+* Delete a project:
+
+ ```{r}
+ deletedProject <- arv$deleteProject("uuid")
+ ```
+
+* Update project:
+
+ ```{r}
+ updatedProject <- arv$updateProject("uuid", list(name = "new_name", description = "new description"))
+ ```
+
+* Create project:
+
+ ```{r}
+ createdProject <- arv$createProject(list(name = "project_name", description = "project description"))
+ ```
+
+### Building the ArvadosR package
+
+ ```
+ cd arvados/sdk && R CMD build R
+ ```
+
+This will create a tarball of the ArvadosR package in the current directory.
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/Arvados.R
-\docType{data}
\name{Arvados}
\alias{Arvados}
-\title{Arvados SDK Object}
-\format{An object of class \code{R6ClassGenerator} of length 24.}
-\usage{
-Arvados
-}
+\title{Arvados}
\description{
-All Arvados logic is inside this class
+Arvados class gives users ability to manipulate collections and projects.
+}
+\section{Usage}{
+
+\preformatted{arv = Arvados$new(authToken = NULL, hostName = NULL, numRetries = 0)}
}
-\section{Fields}{
+
+\section{Arguments}{
\describe{
-\item{\code{token}}{Token represents user authentification token.}
+ \item{authToken}{Authentification token. If not specified ARVADOS_API_TOKEN environment variable will be used.}
+ \item{hostName}{Host name. If not specified ARVADOS_API_HOST environment variable will be used.}
+ \item{numRetries}{Number which specifies how many times to retry failed service requests.}
+}
+}
-\item{\code{host}}{Host represents server name we wish to connect to.}
-}}
+\section{Methods}{
+
+\describe{
+ \item{getToken()}{Returns authentification token currently in use.}
+ \item{getHostName()}{Returns host name currently in use.}
+ \item{getNumRetries()}{Returns number which specifies how many times to retry failed service requests.}
+ \item{setNumRetries(newNumOfRetries)}{Sets number which specifies how many times to retry failed service requests.}
+ \item{getCollection(uuid)}{Get collection with specified UUID.}
+ \item{listCollections(filters = NULL, limit = 100, offset = 0)}{Returns list of collections based on filters parameter.}
+ \item{listAllCollections(filters = NULL)}{Lists all collections, based on filters parameter, even if the number of items is greater than maximum API limit.}
+ \item{deleteCollection(uuid)}{Deletes collection with specified UUID.}
+ \item{updateCollection(uuid, newContent)}{Updates collection with specified UUID.}
+ \item{createCollection(content)}{Creates new collection.}
+ \item{getProject(uuid)}{Get project with specified UUID.}
+ \item{listProjects(filters = NULL, limit = 100, offset = 0)}{Returns list of projects based on filters parameter.}
+ \item{listAllProjects(filters = NULL)}{Lists all projects, based on filters parameter, even if the number of items is greater than maximum API limit.}
+ \item{deleteProject(uuid)}{Deletes project with specified UUID.}
+ \item{updateProject(uuid, newContent)}{Updates project with specified UUID.}
+ \item{createProject(content)}{Creates new project.}
+}
+}
\examples{
-arv = Arvados$new("token", "host_name")
+\dontrun{
+arv <- Arvados$new("your Arvados token", "example.arvadosapi.com")
+
+collection <- arv$getCollection("uuid")
+
+collectionList <- arv$listCollections(list(list("name", "like", "Test\%")))
+collectionList <- arv$listAllCollections(list(list("name", "like", "Test\%")))
+
+deletedCollection <- arv$deleteCollection("uuid")
+
+updatedCollection <- arv$updateCollection("uuid", list(name = "New name",
+ description = "New description"))
+
+createdCollection <- arv$createCollection(list(name = "Example",
+ description = "This is a test collection"))
+}
}
-\keyword{datasets}
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/ArvadosFile.R
-\docType{data}
\name{ArvadosFile}
\alias{ArvadosFile}
-\title{ArvadosFile Object}
-\format{An object of class \code{R6ClassGenerator} of length 24.}
-\usage{
-ArvadosFile
-}
+\title{ArvadosFile}
\description{
-Update description
+ArvadosFile class represents a file inside Arvados collection.
+}
+\section{Usage}{
+
+\preformatted{file = ArvadosFile$new(name)}
+}
+
+\section{Arguments}{
+
+\describe{
+ \item{name}{Name of the file.}
+}
+}
+
+\section{Methods}{
+
+\describe{
+ \item{getName()}{Returns name of the file.}
+ \item{getRelativePath()}{Returns file path relative to the root.}
+ \item{read(contentType = "raw", offset = 0, length = 0)}{Read file content.}
+ \item{write(content, contentType = "text/html")}{Write to file (override current content of the file).}
+ \item{connection(rw)}{Get connection opened in "read" or "write" mode.}
+ \item{flush()}{Write connections content to a file (override current content of the file).}
+ \item{remove(name)}{Removes ArvadosFile or Subcollection specified by name from the subcollection.}
+ \item{getSizeInBytes()}{Returns file size in bytes.}
+ \item{move(newLocation)}{Moves file to a new location inside collection.}
+}
+}
+
+\examples{
+\dontrun{
+myFile <- ArvadosFile$new("myFile")
+
+myFile$write("This is new file content")
+fileContent <- myFile$read()
+fileContent <- myFile$read("text")
+fileContent <- myFile$read("raw", offset = 8, length = 4)
+
+#Write a table:
+arvConnection <- myFile$connection("w")
+write.table(mytable, arvConnection)
+arvadosFile$flush()
+
+#Read a table:
+arvConnection <- myFile$connection("r")
+mytable <- read.table(arvConnection)
+
+myFile$move("newFolder/myFile")
+}
}
-\keyword{datasets}
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/Collection.R
-\docType{data}
\name{Collection}
\alias{Collection}
-\title{Arvados Collection Object}
-\format{An object of class \code{R6ClassGenerator} of length 24.}
-\usage{
-Collection
-}
+\title{Collection}
\description{
-Update description
+Collection class provides interface for working with Arvados collections.
+}
+\section{Usage}{
+
+\preformatted{collection = Collection$new(arv, uuid)}
+}
+
+\section{Arguments}{
+
+\describe{
+ \item{arv}{Arvados object.}
+ \item{uuid}{UUID of a collection.}
+}
}
+
+\section{Methods}{
+
+\describe{
+ \item{add(content)}{Adds ArvadosFile or Subcollection specified by content to the collection.}
+ \item{create(fileNames, relativePath = "")}{Creates one or more ArvadosFiles and adds them to the collection at specified path.}
+ \item{remove(fileNames)}{Remove one or more files from the collection.}
+ \item{move(content, newLocation)}{Moves ArvadosFile or Subcollection to another location in the collection.}
+ \item{getFileListing()}{Returns collections file content as character vector.}
+ \item{get(relativePath)}{If relativePath is valid, returns ArvadosFile or Subcollection specified by relativePath, else returns NULL.}
+}
+}
+
\examples{
-arv = Collection$new(api, uuid)
+\dontrun{
+arv <- Arvados$new("your Arvados token", "example.arvadosapi.com")
+collection <- Collection$new(arv, "uuid")
+
+newFile <- ArvadosFile$new("myFile")
+collection$add(newFile, "myFolder")
+
+createdFiles <- collection$create(c("main.cpp", lib.dll), "cpp/src/")
+
+collection$remove("location/to/my/file.cpp")
+
+collection$move("folder/file.cpp", "file.cpp")
+
+arvadosFile <- collection$get("location/to/my/file.cpp")
+arvadosSubcollection <- collection$get("location/to/my/directory/")
+}
}
-\keyword{datasets}
+++ /dev/null
-% Generated by roxygen2: do not edit by hand
-% Please edit documentation in R/CollectionTree.R
-\docType{data}
-\name{CollectionTree}
-\alias{CollectionTree}
-\title{Arvados Collection Object}
-\format{An object of class \code{R6ClassGenerator} of length 24.}
-\usage{
-CollectionTree
-}
-\description{
-Update description
-}
-\examples{
-arv = Collection$new(api, uuid)
-}
-\keyword{datasets}
+++ /dev/null
-% Generated by roxygen2: do not edit by hand
-% Please edit documentation in R/HttpParser.R
-\docType{data}
-\name{HttpParser}
-\alias{HttpParser}
-\title{HttpParser}
-\format{An object of class \code{R6ClassGenerator} of length 24.}
-\usage{
-HttpParser
-}
-\description{
-HttpParser
-}
-\keyword{datasets}
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/Subcollection.R
-\docType{data}
\name{Subcollection}
\alias{Subcollection}
-\title{Arvados SubCollection Object}
-\format{An object of class \code{R6ClassGenerator} of length 24.}
-\usage{
-Subcollection
-}
+\title{Subcollection}
\description{
-Update description
+Subcollection class represents a folder inside Arvados collection.
+It is essentially a composite of ArvadosFiles and other Subcollections.
+}
+\section{Usage}{
+
+\preformatted{subcollection = Subcollection$new(name)}
+}
+
+\section{Arguments}{
+
+\describe{
+ \item{name}{Name of the subcollection.}
+}
+}
+
+\section{Methods}{
+
+\describe{
+ \item{getName()}{Returns name of the subcollection.}
+ \item{getRelativePath()}{Returns subcollection path relative to the root.}
+ \item{add(content)}{Adds ArvadosFile or Subcollection specified by content to the subcollection.}
+ \item{remove(name)}{Removes ArvadosFile or Subcollection specified by name from the subcollection.}
+ \item{get(relativePath)}{If relativePath is valid, returns ArvadosFile or Subcollection specified by relativePath, else returns NULL.}
+ \item{getFileListing()}{Returns subcollections file content as character vector.}
+ \item{getSizeInBytes()}{Returns subcollections content size in bytes.}
+ \item{move(newLocation)}{Moves subcollection to a new location inside collection.}
+}
+}
+
+\examples{
+\dontrun{
+myFolder <- Subcollection$new("myFolder")
+myFile <- ArvadosFile$new("myFile")
+
+myFolder$add(myFile)
+myFolder$get("myFile")
+myFolder$remove("myFile")
+
+myFolder$move("newLocation/myFolder")
+}
}
-\keyword{datasets}
--- /dev/null
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/Arvados.R
+\name{print.Arvados}
+\alias{print.Arvados}
+\title{print.Arvados}
+\usage{
+\method{print}{Arvados}(x, ...)
+}
+\arguments{
+\item{x}{Instance of Arvados class}
+
+\item{...}{Optional arguments.}
+}
+\description{
+Custom print function for Arvados class
+}
--- /dev/null
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/ArvadosFile.R
+\name{print.ArvadosFile}
+\alias{print.ArvadosFile}
+\title{print.ArvadosFile}
+\usage{
+\method{print}{ArvadosFile}(x, ...)
+}
+\arguments{
+\item{x}{Instance of ArvadosFile class}
+
+\item{...}{Optional arguments.}
+}
+\description{
+Custom print function for ArvadosFile class
+}
--- /dev/null
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/Collection.R
+\name{print.Collection}
+\alias{print.Collection}
+\title{print.Collection}
+\usage{
+\method{print}{Collection}(x, ...)
+}
+\arguments{
+\item{x}{Instance of Collection class}
+
+\item{...}{Optional arguments.}
+}
+\description{
+Custom print function for Collection class
+}
--- /dev/null
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/Subcollection.R
+\name{print.Subcollection}
+\alias{print.Subcollection}
+\title{print.Subcollection}
+\usage{
+\method{print}{Subcollection}(x, ...)
+}
+\arguments{
+\item{x}{Instance of Subcollection class}
+
+\item{...}{Optional arguments.}
+}
+\description{
+Custom print function for Subcollection class
+}
PIPCACHE="$ARVBOX_DATA/pip"
NPMCACHE="$ARVBOX_DATA/npm"
GOSTUFF="$ARVBOX_DATA/gopath"
+RLIBS="$ARVBOX_DATA/Rlibs"
getip() {
docker inspect $ARVBOX_CONTAINER | grep \"IPAddress\" | head -n1 | tr -d ' ":,\n' | cut -c10-
updateconf
wait_for_arvbox
else
- mkdir -p "$PG_DATA" "$VAR_DATA" "$PASSENGER" "$GEMS" "$PIPCACHE" "$NPMCACHE" "$GOSTUFF"
+ mkdir -p "$PG_DATA" "$VAR_DATA" "$PASSENGER" "$GEMS" "$PIPCACHE" "$NPMCACHE" "$GOSTUFF" "$RLIBS"
if ! test -d "$ARVADOS_ROOT" ; then
"--volume=$PIPCACHE:/var/lib/pip:rw" \
"--volume=$NPMCACHE:/var/lib/npm:rw" \
"--volume=$GOSTUFF:/var/lib/gopath:rw" \
+ "--volume=$RLIBS:/var/lib/Rlibs:rw" \
"--env=SVDIR=/etc/test-service" \
arvados/arvbox-dev$TAG
"--volume=$PIPCACHE:/var/lib/pip:rw" \
"--volume=$NPMCACHE:/var/lib/npm:rw" \
"--volume=$GOSTUFF:/var/lib/gopath:rw" \
+ "--volume=$RLIBS:/var/lib/Rlibs:rw" \
$PUBLIC \
arvados/arvbox-dev$TAG
updateconf
apt-transport-https ca-certificates slurm-wlm \
linkchecker python3-virtualenv python-virtualenv xvfb iceweasel \
libgnutls28-dev python3-dev vim cadaver cython gnupg dirmngr \
- libsecret-1-dev r-base r-cran-testthat libxml2-dev && \
+ libsecret-1-dev r-base r-cran-testthat libxml2-dev pandoc && \
apt-get clean
ENV RUBYVERSION_MINOR 2.3
export GEM_PATH=/var/lib/gems
export npm_config_cache=/var/lib/npm
export npm_config_cache_min=Infinity
+export R_LIBS=/var/lib/Rlibs
if test -s /var/run/localip_override ; then
localip=$(cat /var/run/localip_override)
cd /usr/src/arvados/doc
run_bundler --without=development
+cd /usr/src/arvados/sdk/R
+R --quiet --vanilla <<EOF
+options(repos=structure(c(CRAN="http://cran.wustl.edu/")))
+if (!requireNamespace("devtools")) {
+ install.packages("devtools")
+}
+if (!requireNamespace("roxygen2")) {
+ install.packages("roxygen2")
+}
+if (!requireNamespace("pkgdown")) {
+ devtools::install_github("hadley/pkgdown")
+}
+devtools::install_dev_deps()
+EOF
+
if test "$1" = "--only-deps" ; then
exit
fi
}
EOF
+cd /usr/src/arvados/doc
bundle exec rake generate baseurl=http://$localip:${services[doc]} arvados_api_host=$localip:${services[api]} arvados_workbench_host=http://$localip
exec nginx -c /var/lib/arvados/doc-nginx.conf
projects / arvados.git / commitdiff