+[comment]: # (Copyright (c) The Arvados Authors. All rights reserved.)
+[comment]: # ()
+[comment]: # (SPDX-License-Identifier: CC-BY-SA-3.0)
+
## 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
+### Installation
+
+```{r include=FALSE}
+knitr::opts_chunk$set(eval=FALSE)
+```
+
+```{r}
+install.packages("ArvadosR", repos=c("https://r.arvados.org", getOption("repos")["CRAN"]), dependencies=TRUE)
+```
-1. Install the dependencies
+Note: on Linux, you may have to install supporting packages.
- `install.packages(c('R6', 'httr', 'stringr', 'jsonlite', 'curl', 'XML'))`
+On Centos 7, this is:
- 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
+```{bash}
+yum install libxml2-devel openssl-devel curl-devel
+```
+On Debian, this is:
-2. Install the ArvardosR package
+```{bash}
+apt-get install build-essential libxml2-dev libssl-dev libcurl4-gnutls-dev
+```
- `install.packages('http://r.arvados.org/ArvadosR_0.0.3.tar.gz', repos=NULL, type='source')`
+Minimum R version required to run ArvadosR is 3.3.0.
-### EXAMPLES OF USAGE
-#### INITIALIZING API
+### Usage
+
+#### Initializing API
* 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")`
+```{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.
+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)`
+```{r}
+arv <- Arvados$new("your Arvados token", "example.arvadosapi.com", numRetries = 3)
+```
- This parameter can be set at any time using setNumRetries
+This parameter can be set at any time using setNumRetries
- `arv$setNumRetries(5)`
+```{r}
+arv$setNumRetries(5)
+```
-#### WORKING WITH COLLECTIONS
+#### Working with collections
* Get a collection:
- `collection <- arv$getCollection("uuid")`
+```{r}
+collection <- arv$collections.get("uuid")
+```
+
+Be aware that the result from `collections.get` is _not_ a
+`Collection` class. The object returned from this method lets you
+access collection fields like "name" and "description". The
+`Collection` class lets you access the files in the collection for
+reading and writing, and is described in the next section.
* 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)`
+```{r}
+# offset of 0 and default limit of 100
+collectionList <- arv$collections.list(list(list("name", "like", "Test%")))
- `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`
+collectionList <- arv$collections.list(list(list("name", "like", "Test%")), limit = 10, offset = 2)
+
+# 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:
- `collectionList <- arv$listAllCollections(list(list("name", "like", "Test%")))`
+```{r}
+collectionList <- listAll(arv$collections.list, list(list("name", "like", "Test%")))
+```
* Delete a collection:
- `deletedCollection <- arv$deleteCollection("uuid")`
+```{r}
+deletedCollection <- arv$collections.delete("uuid")
+```
* Update a collection's metadata:
- `updatedCollection <- arv$updateCollection("uuid", list(name = "New name", description = "New description"))`
+```{r}
+updatedCollection <- arv$collections.update(list(name = "New name", description = "New description"), "uuid")
+```
-* Create collection:
+* Create a new collection:
- `createdCollection <- arv$createCollection(list(name = "Example", description = "This is a test collection"))`
+```{r}
+newCollection <- arv$collections.create(list(name = "Example", description = "This is a test collection"))
+```
-#### MANIPULATIN COLLECTION CONTENT
+#### Manipulating collection content
-* Create collection object:
+* Initialize a collection object:
- `collection <- Collection$new(arv, "uuid")`
+```{r}
+collection <- Collection$new(arv, "uuid")
+```
* Get list of files:
- `files <- collection$getFileListing()`
+```{r}
+files <- collection$getFileListing()
+```
* Get ArvadosFile or Subcollection from internal tree-like structure:
- `arvadosFile <- collection$get("location/to/my/file.cpp")`
+```{r}
+arvadosFile <- collection$get("location/to/my/file.cpp")
+```
- or
+or
- `arvadosSubcollection <- collection$get("location/to/my/directory/")`
+```{r}
+arvadosSubcollection <- collection$get("location/to/my/directory/")
+```
* Read a table:
- `arvadosFile <- collection$get("myinput.txt")`
- `arvConnection <- arvadosFile$connection("r")`
- `mytable <- read.table(arvConnection)`
+```{r}
+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()`
+```{r}
+arvadosFile <- collection$create("myoutput.txt")[[1]]
+arvConnection <- arvadosFile$connection("w")
+write.table(mytable, arvConnection)
+arvadosFile$flush()
+```
-* Write to existing file (override current content of the file):
+* Write to existing file (overwrites current content of the file):
- `arvadosFile <- collection$get("location/to/my/file.cpp")`
- `arvadosFile$write("This is new file content")`
+```{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:
- `fileContent <- arvadosFile$read()`
- `fileContent <- arvadosFile$read("text")`
- `fileContent <- arvadosFile$read("raw", offset = 1024, length = 512)`
+```{r}
+fileContent <- arvadosFile$read()
+fileContent <- arvadosFile$read("text")
+fileContent <- arvadosFile$read("raw", offset = 1024, length = 512)
+```
* Get ArvadosFile or Subcollection size:
- `size <- arvadosFile$getSizeInBytes()`
+```{r}
+size <- arvadosFile$getSizeInBytes()
+```
- or
+or
- `size <- arvadosSubcollection$getSizeInBytes()`
+```{r}
+size <- arvadosSubcollection$getSizeInBytes()
+```
-* Create new file in a collection:
+* Create new file in a collection (returns a vector of one or more ArvadosFile objects):
- `collection$create(fileNames, optionalRelativePath)`
+```{r}
+collection$create(files)
+```
- Example:
+Example:
- `mainFile <- collection$create("main.cpp", "cpp/src/")`
- `fileList <- collection$create(c("main.cpp", lib.dll), "cpp/src/")`
+```{r}
+mainFile <- collection$create("cpp/src/main.cpp")[[1]]
+fileList <- collection$create(c("cpp/src/main.cpp", "cpp/src/util.h"))
+```
-* Add existing ArvadosFile or Subcollection to a collection:
+* Delete file from a collection:
- `folder <- Subcollection$new("src")`
- `file <- ArvadosFile$new("main.cpp")`
- `folder$add(file)`
+```{r}
+collection$remove("location/to/my/file.cpp")
+```
- `collection$add(folder, "cpp")`
+You can remove both Subcollection and ArvadosFile.
+If subcollection contains more files or folders they will be removed recursively.
- 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.
+You can also remove multiple files at once:
-* Delete file from a collection:
+```{r}
+collection$remove(c("path/to/my/file.cpp", "path/to/other/file.cpp"))
+```
- `collection$remove("location/to/my/file.cpp")`
+* Delete file or folder from a Subcollection:
- You can remove both Subcollection and ArvadosFile.
- If subcollection contains more files or folders they will be removed recursively.
+```{r}
+subcollection <- collection$get("mySubcollection/")
+subcollection$remove("fileInsideSubcollection.exe")
+subcollection$remove("folderInsideSubcollection/")
+```
- You can also remove multiple files at once:
+* Move or rename a file or folder within a collection (moving between collections is currently not supported):
- `collection$remove(c("path/to/my/file.cpp", "path/to/other/file.cpp"))`
+Directly from collection
-* Delete file or folder from a Subcollection:
+```{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")
+```
- `subcollection <- collection$get("mySubcollection/")`
- `subcollection$remove("fileInsideSubcollection.exe")`
- `subcollection$remove("folderInsideSubcollection/")`
+Or from subcollection
-* Move file or folder inside collection:
+```{r}
+subcollection <- collection$get("location/to/folder")
+subcollection$move("newDestination/folder")
+```
- Directley from collection
+Make sure to include new file name in destination.
+In second example file$move("newDestination/") will not work.
- `collection$move("folder/file.cpp", "file.cpp")`
+* Copy file or folder within a collection (copying between collections is currently not supported):
- Or from file
+Directly from collection
- `file <- collection$get("location/to/my/file.cpp")`
- `file$move("newDestination/file.cpp")`
+```{r}
+collection$copy("folder/file.cpp", "file.cpp")
+```
- Or from subcollection
+Or from file
- `subcollection <- collection$get("location/to/folder")`
- `subcollection$move("newDestination/folder")`
+```{r}
+file <- collection$get("location/to/my/file.cpp")
+file$copy("destination/file.cpp")
+```
- Make sure to include new file name in destination.
- In second example file$move("newDestination/") will not work.
+Or from subcollection
-#### WORKING WITH ARVADOS PROJECTS
+```{r}
+subcollection <- collection$get("location/to/folder")
+subcollection$copy("destination/folder")
+```
+
+#### Working with Aravdos projects
* Get a project:
- `project <- arv$getProject("uuid")`
+```{r}
+project <- arv$projects.get("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`
+```{r}
+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:
- `collectionList <- arv$listAllProjects(list(list("name","like","Example%")))`
+```{r}
+projects <- listAll(arv$projects.list, list(list("name","like","Example%")))
+```
* Delete a project:
- `deletedProject <- arv$deleteProject("uuid")`
+```{r}
+deletedProject <- arv$projects.delete("uuid")
+```
* Update project:
- `updatedProject <- arv$updateProject("uuid", list(name = "new_name", description = "new description"))`
+```{r}
+updatedProject <- arv$projects.update(list(name = "new_name", description = "new description"), "uuid")
+```
* Create project:
- `createdProject <- arv$createProject(list(name = "project_name", description = "project description"))`
+```{r}
+newProject <- arv$projects.update(list(name = "project_name", description = "project description"))
+```
+
+#### Help
+
+* View help page of Arvados classes by puting ? before class name:
+
+```{r}
+?Arvados
+?Collection
+?Subcollection
+?ArvadosFile
+```
+
+* View help page of any method defined in Arvados class by puting ? before method name:
+
+```{r}
+?collections.update
+?jobs.get
+```
-### BUILDING THE ARVADOS SDK TARBALL
+### Building the ArvadosR package
-cd arvados/sdk
-R CMD build R
+```{bash}
+cd arvados/sdk && R CMD build R
+```
-This will create a tarball of the Arvados package in the current directory.
+This will create a tarball of the ArvadosR package in the current directory.
projects / arvados.git / blobdiff