### Installation
-```install.packages("ArvadosR", repos=c("http://r.arvados.org", getOption("repos")["CRAN"]), dependencies=TRUE)```
+```{r include=FALSE}
+knitr::opts_chunk$set(eval=FALSE)
+```
+
+```{r}
+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```
+```{bash}
+yum install libxml2-devel openssl-devel curl-devel
+```
On Debian, this is:
-```apt-get install build-essential libxml2-dev libssl-dev libcurl4-gnutls-dev```
+```{bash}
+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()
+```{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")
- ```
+# 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.
- ```{r}
- 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
- ```{r}
- arv$setNumRetries(5)
- ```
+```{r}
+arv$setNumRetries(5)
+```
#### Working with collections
* Get a collection:
- ```{r}
- collection <- arv$collections.get("uuid")
- ```
+```{r}
+collection <- arv$collections.get("uuid")
+```
* List collections:
- ```{r}
- # offset of 0 and default limit of 100
- collectionList <- arv$collections.list(list(list("name", "like", "Test%")))
+```{r}
+# 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)
- ```
+collectionList <- arv$collections.list(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
+```{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
- ```
+# 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 <- listAll(arv$collections.list, list(list("name", "like", "Test%")))
- ```
+```{r}
+collectionList <- listAll(arv$collections.list, list(list("name", "like", "Test%")))
+```
* Delete a collection:
- ```{r}
- deletedCollection <- arv$collections.delete("uuid")
- ```
+```{r}
+deletedCollection <- arv$collections.delete("uuid")
+```
* Update a collection's metadata:
- ```{r}
- updatedCollection <- arv$collections.update(list(name = "New name", description = "New description"), "uuid")
- ```
+```{r}
+updatedCollection <- arv$collections.update(list(name = "New name", description = "New description"), "uuid")
+```
* Create collection:
- ```{r}
- newCollection <- arv$collections.create(list(name = "Example", description = "This is a test collection"))
- ```
+```{r}
+newCollection <- arv$collections.create(list(name = "Example", description = "This is a test collection"))
+```
#### Manipulating collection content
* Create collection object:
- ```{r}
- collection <- Collection$new(arv, "uuid")
- ```
+```{r}
+collection <- Collection$new(arv, "uuid")
+```
* Get list of files:
- ```{r}
- files <- collection$getFileListing()
- ```
+```{r}
+files <- collection$getFileListing()
+```
* Get ArvadosFile or Subcollection from internal tree-like structure:
- ```{r}
- arvadosFile <- collection$get("location/to/my/file.cpp")
- ```
+```{r}
+arvadosFile <- collection$get("location/to/my/file.cpp")
+```
or
- ```{r}
- arvadosSubcollection <- collection$get("location/to/my/directory/")
- ```
+```{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)
- ```
+```{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()
- ```
+```{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")
- ```
+```{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)
- ```
+```{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()
- ```
+```{r}
+size <- arvadosFile$getSizeInBytes()
+```
or
- ```{r}
- size <- arvadosSubcollection$getSizeInBytes()
- ```
+```{r}
+size <- arvadosSubcollection$getSizeInBytes()
+```
* Create new file in a collection:
- ```{r}
- collection$create(fileNames, optionalRelativePath)
- ```
+```{r}
+collection$create(fileNames, optionalRelativePath)
+```
Example:
- ```{r}
- mainFile <- collection$create("main.cpp", "cpp/src/")
- fileList <- collection$create(c("main.cpp", lib.dll), "cpp/src/")
- ```
+```{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}
+folder <- Subcollection$new("src")
+file <- ArvadosFile$new("main.cpp")
+folder$add(file)
+```
- ```{r}
- collection$add(folder, "cpp")
- ```
+```{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.
+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")
- ```
+```{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 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:
+You can also remove multiple files at once:
- ```{r}
- collection$remove(c("path/to/my/file.cpp", "path/to/other/file.cpp"))
- ```
+```{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/")
- ```
+```{r}
+subcollection <- collection$get("mySubcollection/")
+subcollection$remove("fileInsideSubcollection.exe")
+subcollection$remove("folderInsideSubcollection/")
+```
* Move file or folder inside collection:
- Directley from collection
+Directley from collection
- ```{r}
- collection$move("folder/file.cpp", "file.cpp")
- ```
+```{r}
+collection$move("folder/file.cpp", "file.cpp")
+```
- Or from file
+Or from file
- ```{r}
- file <- collection$get("location/to/my/file.cpp")
- file$move("newDestination/file.cpp")
- ```
+```{r}
+file <- collection$get("location/to/my/file.cpp")
+file$move("newDestination/file.cpp")
+```
- Or from subcollection
+Or from subcollection
- ```{r}
- subcollection <- collection$get("location/to/folder")
- subcollection$move("newDestination/folder")
- ```
+```{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.
+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$projects.get("uuid")
- ```
+```{r}
+project <- arv$projects.get("uuid")
+```
* List projects:
- ```{r}
- # list subprojects of a project
- projects <- arv$projects.list(list(list("owner_uuid", "=", "aaaaa-j7d0g-ccccccccccccccc")))
+```{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 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:
- ```{r}
- projects <- listAll(arv$projects.list, list(list("name","like","Example%")))
- ```
+```{r}
+projects <- listAll(arv$projects.list, list(list("name","like","Example%")))
+```
* Delete a project:
- ```{r}
- deletedProject <- arv$projects.delete("uuid")
- ```
+```{r}
+deletedProject <- arv$projects.delete("uuid")
+```
* Update project:
- ```{r}
- updatedProject <- arv$projects.update(list(name = "new_name", description = "new description"), "uuid")
- ```
+```{r}
+updatedProject <- arv$projects.update(list(name = "new_name", description = "new description"), "uuid")
+```
* Create project:
- ```{r}
- newProject <- arv$projects.update(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
- ```
+```{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
- ```
+```{r}
+?collections.update
+?jobs.get
+```
### 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 ArvadosR package in the current directory.
projects / arvados.git / blobdiff