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")

--------------------------------------------------------------------------------------------------------------------------------

#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

--------------------------------------------------------------------------------------------------------------------------------

#Delete a collection:

deletedCollection <- arv$deleteCollection("uuid")

--------------------------------------------------------------------------------------------------------------------------------

#Update a collection's metadata:

updatedCollection <- arv$updateCollection("uuid", list(name = "My new name", description = "a brand 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

file <- collection$get("location/to/my/file.cpp")

collection$remove(file)

#Or

collection$remove("location/to/my/file.cpp")

#Both examples will remove file "file.cpp" from a collection
#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

file <- collection$get("location/to/my/file.cpp")

file$move("destination/file.cpp")

#Or subcollections

subcollection <- collection$get("location/to/folder")

subcollection$move("destination/folder")

#Make sure to include folder name in destination
#For example
#file$move("destination/") 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

--------------------------------------------------------------------------------------------------------------------------------

#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.