1 [comment]: # (Copyright © The Arvados Authors. All rights reserved.)
3 [comment]: # (SPDX-License-Identifier: CC-BY-SA-3.0)
7 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.
13 * Working with collections
14 * Manipulating collection content
15 * Working with Arvados projects
17 * Building the ArvadosR package
21 Minimum R version required to run ArvadosR is 3.3.0.
24 install.packages("ArvadosR", repos=c("https://r.arvados.org", getOption("repos")["CRAN"]), dependencies=TRUE)
29 > On Linux, you may have to install supporting packages.
31 > On Red Hat, AlmaLinux, and Rocky Linux, this is:
33 > yum install libxml2-devel openssl-devel curl-devel
36 > On Debian and Ubuntu, this is:
38 > apt-get install build-essential libxml2-dev libssl-dev libcurl4-gnutls-dev
47 # use environment variables ARVADOS_API_TOKEN and ARVADOS_API_HOST
50 # provide them explicitly
51 arv <- Arvados$new("your Arvados token", "example.arvadosapi.com")
54 Optionally, add `numRetries` parameter to specify number of times to retry failed service requests. Default is 0.
57 arv <- Arvados$new("your Arvados token", "example.arvadosapi.com", numRetries = 3)
60 This parameter can be set at any time using `setNumRetries`
66 ### Working with Aravdos projects
71 newProject <- arv$project_create(name = "project name", description = "project description", owner_uuid = "project UUID", properties = NULL, ensureUniqueName = "false")
77 updatedProject <- arv$project_update(name = "new project name", properties = newProperties, uuid = "projectUUID")
80 ##### Delete a project:
83 deletedProject <- arv$project_delete("uuid")
91 project <- arv$project_get("uuid")
97 list subprojects of a project
98 projects <- arv$project_list(list(list("owner_uuid", "=", "aaaaa-j7d0g-ccccccccccccccc")))
100 list projects which have names beginning with Example
101 examples <- arv$project_list(list(list("name","like","Example%")))
104 ##### List all projects even if the number of items is greater than maximum API limit:
107 projects <- listAll(arv$project_list, list(list("name","like","Example%")))
110 ### Working with collections
112 #### Create a new collection:
115 newCollection <- arv$collections_create(name = "collectionTitle", description = "collectionDescription", ownerUUID = "collectionOwner", properties = Properties)
118 #### Update a collection’s metadata:
121 collection <- arv$collections_update(name = "newCollectionTitle", description = "newCollectionDescription", ownerUUID = "collectionOwner", properties = NULL, uuid = "collectionUUID")
124 #### Delete a collection:
127 deletedCollection <- arv$collections_delete("uuid")
130 #### Find a collection:
132 #### Get a collection:
135 collection <- arv$collections_get("uuid")
138 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.
140 #### List collections:
143 # offset of 0 and default limit of 100
144 collectionList <- arv$collections_list(list(list("name", "like", "Test%")))
146 collectionList <- arv$collections_list(list(list("name", "like", "Test%")), limit = 10, offset = 2)
148 # count of total number of items (may be more than returned due to paging)
149 collectionList$items_available
151 # items which match the filter criteria
155 #### List all collections even if the number of items is greater than maximum API limit:
158 collectionList <- listAll(arv$collections_list, list(list("name", "like", "Test%")))
161 ### Manipulating collection content
163 #### Initialize a collection object:
166 collection <- Collection$new(arv, "uuid")
169 #### Get list of files:
172 files <- collection$getFileListing()
175 #### Get ArvadosFile or Subcollection from internal tree-like structure:
178 arvadosFile <- collection$get("location/to/my/file.cpp")
180 arvadosSubcollection <- collection$get("location/to/my/directory/")
186 arvadosFile <- collection$get("myinput.txt")
187 arvConnection <- arvadosFile$connection("r")
188 mytable <- read.table(arvConnection)
194 arvadosFile <- collection$create("myoutput.txt")[[1]]
195 arvConnection <- arvadosFile$connection("w")
196 write.table(mytable, arvConnection)
200 #### Read a table from a tab delimited file:
203 arvadosFile <- collection$get("myinput.txt")
204 arvConnection <- arvadosFile$connection("r")
205 mytable <- read.delim(arvConnection)
208 #### Read a gzip compressed R object:
211 obj <- readRDS(gzcon(coll$get("abc.RDS")$connection("rb")))
214 #### Write to existing file (overwrites current content of the file):
217 arvadosFile <- collection$get("location/to/my/file.cpp")
218 arvadosFile$write("This is new file content")
221 #### Read whole file or just a portion of it:
224 fileContent <- arvadosFile$read()
225 fileContent <- arvadosFile$read("text")
226 fileContent <- arvadosFile$read("raw", offset = 1024, length = 512)
229 #### Read various file types:
231 Chooses file type based on file name extension. Recognized file extensions: 'txt', 'xlsx', 'csv', 'tsv', 'fasta', 'dat', 'bin', 'rds', 'rdata'.
234 collection <- Collection$new(arv, collectionUUID)
235 readFile <- collection$readArvFile(arvadosFile, istable = 'yes') # table
236 readFile <- collection$readArvFile(arvadosFile, istable = 'no') # text
237 readFile <- collection$readArvFile(arvadosFile) # xlsx, csv, tsv, rds, rdata
238 readFile <- collection$readArvFile(arvadosFile, fileclass = 'fasta') # fasta
239 readFile <- collection$readArvFile(arvadosFile, Ncol= 4, Nrow = 32) # binary data.frame, only numbers
240 readFile <- collection$readArvFile(arvadosFile, Ncol = 5, Nrow = 150, istable = "factor") # binary data.frame with factor or text
243 #### Get ArvadosFile or Subcollection size:
246 size <- arvadosFile$getSizeInBytes()
248 size <- arvadosSubcollection$getSizeInBytes()
251 #### Create new file in a collection (returns a vector of one or more ArvadosFile objects):
254 collection$create(files)
260 mainFile <- collection$create("cpp/src/main.cpp")[[1]]
261 fileList <- collection$create(c("cpp/src/main.cpp", "cpp/src/util.h"))
264 #### Delete file from a collection:
267 collection$remove("location/to/my/file.cpp")
270 You can remove both Subcollection and ArvadosFile. If subcollection contains more files or folders they will be removed recursively.
273 > You can also remove multiple files at once:
275 > collection$remove(c("path/to/my/file.cpp", "path/to/other/file.cpp"))
278 #### Delete file or folder from a Subcollection:
281 subcollection <- collection$get("mySubcollection/")
282 subcollection$remove("fileInsideSubcollection.exe")
283 subcollection$remove("folderInsideSubcollection/")
286 #### Move or rename a file or folder within a collection (moving between collections is currently not supported):
288 ##### Directly from collection
291 collection$move("folder/file.cpp", "file.cpp")
297 file <- collection$get("location/to/my/file.cpp")
298 file$move("newDestination/file.cpp")
301 ##### Or from subcollection
304 subcollection <- collection$get("location/to/folder")
305 subcollection$move("newDestination/folder")
309 > Make sure to include new file name in destination. In second example `file$move(“newDestination/”)` will not work.
311 #### Copy file or folder within a collection (copying between collections is currently not supported):
313 ##### Directly from collection
316 collection$copy("folder/file.cpp", "file.cpp")
322 file <- collection$get("location/to/my/file.cpp")
323 file$copy("destination/file.cpp")
326 ##### Or from subcollection
329 subcollection <- collection$get("location/to/folder")
330 subcollection$copy("destination/folder")
336 #### View help page of Arvados classes by puting `?` before class name:
345 #### View help page of any method defined in Arvados class by puting `?` before method name:
352 <!-- Taka konwencja USAGE -->
354 ## Building the ArvadosR package
360 This will create a tarball of the ArvadosR package in the current directory.
362 <!-- Czy dodawać Documentation / Community / Development and Contributing / Licensing? Ale tylko do części Rowej? Wszystko? Wcale? -->
366 Complete documentation, including the [User Guide](https://doc.arvados.org/user/index.html), [Installation documentation](https://doc.arvados.org/install/index.html), [Administrator documentation](https://doc.arvados.org/admin/index.html) and
367 [API documentation](https://doc.arvados.org/api/index.html) is available at http://doc.arvados.org/
371 Visit [Arvados Community and Getting Help](https://doc.arvados.org/user/getting_started/community.html).
375 [Report a bug](https://dev.arvados.org/projects/arvados/issues/new) on [dev.arvados.org](https://dev.arvados.org).
379 Arvados is Free Software. See [Arvados Free Software Licenses](https://doc.arvados.org/user/copying/copying.html) for information about the open source licenses used in Arvados.