Merge branch '22204-group-sharing' refs #22204
[arvados.git] / sdk / R / README.md
1 [comment]: # (Copyright © The Arvados Authors. All rights reserved.)
2 [comment]: # ()
3 [comment]: # (SPDX-License-Identifier: CC-BY-SA-3.0)
4
5 # R SDK for Arvados
6
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.
8
9 ## Key Topics
10 * Installation
11 * Usage
12   * Initializing API
13   * Working with collections
14   * Manipulating collection content
15   * Working with Arvados projects
16   * Help
17 * Building the ArvadosR package
18
19 ## Installation
20
21 Minimum R version required to run ArvadosR is 3.3.0.
22
23 ```r
24 install.packages("ArvadosR", repos=c("https://r.arvados.org", getOption("repos")["CRAN"]), dependencies=TRUE)
25 library('ArvadosR')
26 ```
27
28 > **Note**
29 > On Linux, you may have to install supporting packages.
30 >
31 > On Red Hat, AlmaLinux, and Rocky Linux, this is:
32 > ```
33 > yum install libxml2-devel openssl-devel curl-devel
34 > ```
35 >
36 > On Debian and Ubuntu, this is:
37 > ```
38 > apt-get install build-essential libxml2-dev libssl-dev libcurl4-gnutls-dev
39 > ```
40
41
42 ## Usage
43
44 ### Initializing API
45
46 ```r
47 # use environment variables ARVADOS_API_TOKEN and ARVADOS_API_HOST
48 arv <- Arvados$new()
49
50 # provide them explicitly
51 arv <- Arvados$new("your Arvados token", "example.arvadosapi.com")
52 ```
53
54 Optionally, add `numRetries` parameter to specify number of times to retry failed service requests. Default is 0.
55
56 ```r
57 arv <- Arvados$new("your Arvados token", "example.arvadosapi.com", numRetries = 3)
58 ```
59
60 This parameter can be set at any time using `setNumRetries`
61
62 ```r
63 arv$setNumRetries(5)
64 ```
65
66 ### Working with Aravdos projects
67
68 ##### Create project:
69
70 ```r
71 newProject <- arv$project_create(name = "project name", description = "project description", owner_uuid = "project UUID", properties = NULL, ensureUniqueName = "false")
72 ```
73
74 ##### Update project:
75
76 ```r
77 updatedProject <- arv$project_update(name = "new project name", properties = newProperties, uuid = "projectUUID")
78 ```
79
80 ##### Delete a project:
81
82 ```r
83 deletedProject <- arv$project_delete("uuid")
84 ```
85
86 #### Find a project:
87
88 ##### Get a project:
89
90 ```r
91 project <- arv$project_get("uuid")
92 ```
93
94 ##### List projects:
95
96 ```r
97 list subprojects of a project
98 projects <- arv$project_list(list(list("owner_uuid", "=", "aaaaa-j7d0g-ccccccccccccccc")))
99
100 list projects which have names beginning with Example
101 examples <- arv$project_list(list(list("name","like","Example%")))
102 ```
103
104 ##### List all projects even if the number of items is greater than maximum API limit:
105
106 ```r
107 projects <- listAll(arv$project_list, list(list("name","like","Example%")))
108 ```
109
110 ### Working with collections
111
112 #### Create a new collection:
113
114 ```r
115 newCollection <- arv$collections_create(name = "collectionTitle", description = "collectionDescription", ownerUUID = "collectionOwner", properties = Properties)
116 ```
117
118 #### Update a collection’s metadata:
119
120 ```r
121 collection <- arv$collections_update(name = "newCollectionTitle", description = "newCollectionDescription", ownerUUID = "collectionOwner", properties = NULL, uuid =  "collectionUUID")
122 ```
123
124 #### Delete a collection:
125
126 ```r
127 deletedCollection <- arv$collections_delete("uuid")
128 ```
129
130 #### Find a collection:
131
132 #### Get a collection:
133
134 ```r
135 collection <- arv$collections_get("uuid")
136 ```
137
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.
139
140 #### List collections:
141
142 ```r
143 # offset of 0 and default limit of 100
144 collectionList <- arv$collections_list(list(list("name", "like", "Test%")))
145
146 collectionList <- arv$collections_list(list(list("name", "like", "Test%")), limit = 10, offset = 2)
147
148 # count of total number of items (may be more than returned due to paging)
149 collectionList$items_available
150
151 # items which match the filter criteria
152 collectionList$items
153 ```
154
155 #### List all collections even if the number of items is greater than maximum API limit:
156
157 ```r
158 collectionList <- listAll(arv$collections_list, list(list("name", "like", "Test%")))
159 ```
160
161 ### Manipulating collection content
162
163 #### Initialize a collection object:
164
165 ```r
166 collection <- Collection$new(arv, "uuid")
167 ```
168
169 #### Get list of files:
170
171 ```r
172 files <- collection$getFileListing()
173 ```
174
175 #### Get ArvadosFile or Subcollection from internal tree-like structure:
176
177 ```r
178 arvadosFile <- collection$get("location/to/my/file.cpp")
179 # or
180 arvadosSubcollection <- collection$get("location/to/my/directory/")
181 ```
182
183 #### Read a table:
184
185 ```r
186 arvadosFile   <- collection$get("myinput.txt")
187 arvConnection <- arvadosFile$connection("r")
188 mytable       <- read.table(arvConnection)
189 ```
190
191 #### Write a table:
192
193 ```r
194 arvadosFile   <- collection$create("myoutput.txt")[[1]]
195 arvConnection <- arvadosFile$connection("w")
196 write.table(mytable, arvConnection)
197 arvadosFile$flush()
198 ```
199
200 #### Read a table from a tab delimited file:
201
202 ```r
203 arvadosFile   <- collection$get("myinput.txt")
204 arvConnection <- arvadosFile$connection("r")
205 mytable       <- read.delim(arvConnection)
206 ```
207
208 #### Read a gzip compressed R object:
209
210 ```r
211 obj <- readRDS(gzcon(coll$get("abc.RDS")$connection("rb")))
212 ```
213
214 #### Write to existing file (overwrites current content of the file):
215
216 ```r
217 arvadosFile <- collection$get("location/to/my/file.cpp")
218 arvadosFile$write("This is new file content")
219 ```
220
221 #### Read whole file or just a portion of it:
222
223 ```r
224 fileContent <- arvadosFile$read()
225 fileContent <- arvadosFile$read("text")
226 fileContent <- arvadosFile$read("raw", offset = 1024, length = 512)
227 ```
228
229 #### Read various file types:
230
231 Chooses file type based on file name extension.  Recognized file extensions: 'txt', 'xlsx', 'csv', 'tsv', 'fasta', 'dat', 'bin', 'rds', 'rdata'.
232
233 ```r
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
241 ```
242
243 #### Get ArvadosFile or Subcollection size:
244
245 ```r
246 size <- arvadosFile$getSizeInBytes()
247 # or
248 size <- arvadosSubcollection$getSizeInBytes()
249 ```
250
251 #### Create new file in a collection (returns a vector of one or more ArvadosFile objects):
252
253 ```r
254 collection$create(files)
255 ```
256
257 **Example**
258
259 ```
260 mainFile <- collection$create("cpp/src/main.cpp")[[1]]
261 fileList <- collection$create(c("cpp/src/main.cpp", "cpp/src/util.h"))
262 ```
263
264 #### Delete file from a collection:
265
266 ```r
267 collection$remove("location/to/my/file.cpp")
268 ```
269
270 You can remove both Subcollection and ArvadosFile. If subcollection contains more files or folders they will be removed recursively.
271
272 > **Note**
273 > You can also remove multiple files at once:
274 > ```
275 > collection$remove(c("path/to/my/file.cpp", "path/to/other/file.cpp"))
276 > ```
277
278 #### Delete file or folder from a Subcollection:
279
280 ```r
281 subcollection <- collection$get("mySubcollection/")
282 subcollection$remove("fileInsideSubcollection.exe")
283 subcollection$remove("folderInsideSubcollection/")
284 ```
285
286 #### Move or rename a file or folder within a collection (moving between collections is currently not supported):
287
288 ##### Directly from collection
289
290 ```r
291 collection$move("folder/file.cpp", "file.cpp")
292 ```
293
294 ##### Or from file
295
296 ```r
297 file <- collection$get("location/to/my/file.cpp")
298 file$move("newDestination/file.cpp")
299 ```
300
301 ##### Or from subcollection
302
303 ```r
304 subcollection <- collection$get("location/to/folder")
305 subcollection$move("newDestination/folder")
306 ```
307
308 > **Note**
309 > Make sure to include new file name in destination. In second example `file$move(“newDestination/”)` will not work.
310
311 #### Copy file or folder within a collection (copying between collections is currently not supported):
312
313 ##### Directly from collection
314
315 ```r
316 collection$copy("folder/file.cpp", "file.cpp")
317 ```
318
319 ##### Or from file
320
321 ```r
322 file <- collection$get("location/to/my/file.cpp")
323 file$copy("destination/file.cpp")
324 ```
325
326 ##### Or from subcollection
327
328 ```r
329 subcollection <- collection$get("location/to/folder")
330 subcollection$copy("destination/folder")
331 ```
332
333
334 ### Help
335
336 #### View help page of Arvados classes by puting `?` before class name:
337
338 ```r
339 ?Arvados
340 ?Collection
341 ?Subcollection
342 ?ArvadosFile
343 ```
344
345 #### View help page of any method defined in Arvados class by puting `?` before method name:
346
347 ```r
348 ?collections_update
349 ?workflows_get
350 ```
351
352  <!-- Taka konwencja USAGE -->
353
354 ## Building the ArvadosR package
355
356 ```
357 make package
358 ```
359
360 This will create a tarball of the ArvadosR package in the current directory.
361
362  <!-- Czy dodawać Documentation / Community / Development and Contributing / Licensing? Ale tylko do części Rowej? Wszystko? Wcale? -->
363
364 ## Documentation
365
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/
368
369 ## Community
370
371 Visit [Arvados Community and Getting Help](https://doc.arvados.org/user/getting_started/community.html).
372
373 ## Reporting bugs
374
375 [Report a bug](https://dev.arvados.org/projects/arvados/issues/new) on [dev.arvados.org](https://dev.arvados.org).
376
377 ## Licensing
378
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.