R SDK Overview

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

1
yum install libxml2-devel openssl-devel curl-devel

On Debian, this is:

1
apt-get install build-essential libxml2-dev libssl-dev libcurl4-gnutls-dev

Minimum R version required to run ArvadosR is 3.3.0.

Usage

Initializing API

  • Load Library and Initialize API:
1
2
3
4
5
6
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.

1
arv <- Arvados$new("your Arvados token", "example.arvadosapi.com", numRetries = 3)

This parameter can be set at any time using setNumRetries

1
arv$setNumRetries(5)

Working with collections

  • Get a collection:
1
collection <- arv$collections.get("uuid")
  • List collections:
1
2
3
4
# offset of 0 and default limit of 100
collectionList <- arv$collections.list(list(list("name", "like", "Test%")))

collectionList <- arv$collections.list(list(list("name", "like", "Test%")), limit = 10, offset = 2)
1
2
3
4
5
# 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:
1
collectionList <- listAll(arv$collections.list, list(list("name", "like", "Test%")))
  • Delete a collection:
1
deletedCollection <- arv$collections.delete("uuid")
  • Update a collection’s metadata:
1
updatedCollection <- arv$collections.update(list(name = "New name", description = "New description"), "uuid")
  • Create collection:
1
newCollection <- arv$collections.create(list(name = "Example", description = "This is a test collection"))

Manipulating collection content

  • Create collection object:
1
collection <- Collection$new(arv, "uuid")
  • Get list of files:
1
files <- collection$getFileListing()
  • Get ArvadosFile or Subcollection from internal tree-like structure:
1
arvadosFile <- collection$get("location/to/my/file.cpp")
or
1
arvadosSubcollection <- collection$get("location/to/my/directory/")
  • Read a table:
1
2
3
arvadosFile   <- collection$get("myinput.txt")
arvConnection <- arvadosFile$connection("r")
mytable       <- read.table(arvConnection)
  • Write a table:
1
2
3
4
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):
1
2
arvadosFile <- collection$get("location/to/my/file.cpp")
arvadosFile$write("This is new file content")
  • Read whole file or just a portion of it:
1
2
3
fileContent <- arvadosFile$read()
fileContent <- arvadosFile$read("text")
fileContent <- arvadosFile$read("raw", offset = 1024, length = 512)
  • Get ArvadosFile or Subcollection size:
1
size <- arvadosFile$getSizeInBytes()
or
1
size <- arvadosSubcollection$getSizeInBytes()
  • Create new file in a collection:
1
collection$create(fileNames, optionalRelativePath)
Example:
1
2
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:
1
2
3
folder <- Subcollection$new("src")
file   <- ArvadosFile$new("main.cpp")
folder$add(file)
1
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:
1
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:

1
collection$remove(c("path/to/my/file.cpp", "path/to/other/file.cpp"))
  • Delete file or folder from a Subcollection:
1
2
3
subcollection <- collection$get("mySubcollection/")
subcollection$remove("fileInsideSubcollection.exe")
subcollection$remove("folderInsideSubcollection/")
  • Move file or folder inside collection:

Directley from collection

1
collection$move("folder/file.cpp", "file.cpp")

Or from file

1
2
file <- collection$get("location/to/my/file.cpp")
file$move("newDestination/file.cpp")

Or from subcollection

1
2
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:
1
project <- arv$projects.get("uuid")
  • List projects:
1
2
3
4
5
list subprojects of a project
projects <- arv$projects.list(list(list("owner_uuid", "=", "aaaaa-j7d0g-ccccccccccccccc")))

list projects which have names beginning with Example
examples <- arv$projects.list(list(list("name","like","Example%")))
  • List all projects even if the number of items is greater than maximum API limit:
1
projects <- listAll(arv$projects.list, list(list("name","like","Example%")))
  • Delete a project:
1
deletedProject <- arv$projects.delete("uuid")
  • Update project:
1
updatedProject <- arv$projects.update(list(name = "new_name", description = "new description"), "uuid")
  • Create project:
1
newProject <- arv$projects.update(list(name = "project_name", description = "project description"))

Help

  • View help page of Arvados classes by puting ? before class name:
1
2
3
4
?Arvados
?Collection
?Subcollection
?ArvadosFile
  • View help page of any method defined in Arvados class by puting ? before method name:
1
2
?collections.update
?jobs.get

Building the ArvadosR package

1
cd arvados/sdk && R CMD build R

This will create a tarball of the ArvadosR package in the current directory.


Previous: Examples Next: R Reference

The content of this documentation is licensed under the Creative Commons Attribution-Share Alike 3.0 United States licence.
Code samples in this documentation are licensed under the Apache License, Version 2.0.