16306: Merge branch 'master'
[arvados.git] / sdk / R / README.Rmd
1 [comment]: # (Copyright (c) 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.
8 The API is not final and feedback is solicited from users on ways in which it could be improved.
9
10 ### Installation
11
12 ```{r include=FALSE}
13 knitr::opts_chunk$set(eval=FALSE)
14 ```
15
16 ```{r}
17 install.packages("ArvadosR", repos=c("https://r.arvados.org", getOption("repos")["CRAN"]), dependencies=TRUE)
18 ```
19
20 Note: on Linux, you may have to install supporting packages.
21
22 On Centos 7, this is:
23
24 ```{bash}
25 yum install libxml2-devel openssl-devel curl-devel
26 ```
27
28 On Debian, this is:
29
30 ```{bash}
31 apt-get install build-essential libxml2-dev libssl-dev libcurl4-gnutls-dev
32 ```
33
34 Minimum R version required to run ArvadosR is 3.3.0.
35
36
37 ### Usage
38
39 #### Initializing API
40
41 * Load Library and Initialize API:
42
43 ```{r}
44 library('ArvadosR')
45 # use environment variables ARVADOS_API_TOKEN and ARVADOS_API_HOST
46 arv <- Arvados$new()
47
48 # provide them explicitly
49 arv <- Arvados$new("your Arvados token", "example.arvadosapi.com")
50 ```
51
52 Optionally, add numRetries parameter to specify number of times to retry failed service requests.
53 Default is 0.
54
55 ```{r}
56 arv <- Arvados$new("your Arvados token", "example.arvadosapi.com", numRetries = 3)
57 ```
58
59 This parameter can be set at any time using setNumRetries
60
61 ```{r}
62 arv$setNumRetries(5)
63 ```
64
65
66 #### Working with collections
67
68 * Get a collection:
69
70 ```{r}
71 collection <- arv$collections.get("uuid")
72 ```
73
74 Be aware that the result from `collections.get` is _not_ a
75 `Collection` class.  The object returned from this method lets you
76 access collection fields like "name" and "description".  The
77 `Collection` class lets you access the files in the collection for
78 reading and writing, and is described in the next section.
79
80 * List collections:
81
82 ```{r}
83 # offset of 0 and default limit of 100
84 collectionList <- arv$collections.list(list(list("name", "like", "Test%")))
85
86 collectionList <- arv$collections.list(list(list("name", "like", "Test%")), limit = 10, offset = 2)
87
88 # count of total number of items (may be more than returned due to paging)
89 collectionList$items_available
90
91 # items which match the filter criteria
92 collectionList$items
93 ```
94
95 * List all collections even if the number of items is greater than maximum API limit:
96
97 ```{r}
98 collectionList <- listAll(arv$collections.list, list(list("name", "like", "Test%")))
99 ```
100
101 * Delete a collection:
102
103 ```{r}
104 deletedCollection <- arv$collections.delete("uuid")
105 ```
106
107 * Update a collection's metadata:
108
109 ```{r}
110 updatedCollection <- arv$collections.update(list(name = "New name", description = "New description"), "uuid")
111 ```
112
113 * Create a new collection:
114
115 ```{r}
116 newCollection <- arv$collections.create(list(name = "Example", description = "This is a test collection"))
117 ```
118
119
120 #### Manipulating collection content
121
122 * Initialize a collection object:
123
124 ```{r}
125 collection <- Collection$new(arv, "uuid")
126 ```
127
128 * Get list of files:
129
130 ```{r}
131 files <- collection$getFileListing()
132 ```
133
134 * Get ArvadosFile or Subcollection from internal tree-like structure:
135
136 ```{r}
137 arvadosFile <- collection$get("location/to/my/file.cpp")
138 ```
139
140 or
141
142 ```{r}
143 arvadosSubcollection <- collection$get("location/to/my/directory/")
144 ```
145
146 * Read a table:
147
148 ```{r}
149 arvadosFile   <- collection$get("myinput.txt")
150 arvConnection <- arvadosFile$connection("r")
151 mytable       <- read.table(arvConnection)
152 ```
153
154 * Write a table:
155
156 ```{r}
157 arvadosFile   <- collection$create("myoutput.txt")[[1]]
158 arvConnection <- arvadosFile$connection("w")
159 write.table(mytable, arvConnection)
160 arvadosFile$flush()
161 ```
162
163 * Write to existing file (overwrites current content of the file):
164
165 ```{r}
166 arvadosFile <- collection$get("location/to/my/file.cpp")
167 arvadosFile$write("This is new file content")
168 ```
169
170 * Read whole file or just a portion of it:
171
172 ```{r}
173 fileContent <- arvadosFile$read()
174 fileContent <- arvadosFile$read("text")
175 fileContent <- arvadosFile$read("raw", offset = 1024, length = 512)
176 ```
177
178 * Get ArvadosFile or Subcollection size:
179
180 ```{r}
181 size <- arvadosFile$getSizeInBytes()
182 ```
183
184 or
185
186 ```{r}
187 size <- arvadosSubcollection$getSizeInBytes()
188 ```
189
190 * Create new file in a collection (returns a vector of one or more ArvadosFile objects):
191
192 ```{r}
193 collection$create(files)
194 ```
195
196 Example:
197
198 ```{r}
199 mainFile <- collection$create("cpp/src/main.cpp")[[1]]
200 fileList <- collection$create(c("cpp/src/main.cpp", "cpp/src/util.h"))
201 ```
202
203 * Delete file from a collection:
204
205 ```{r}
206 collection$remove("location/to/my/file.cpp")
207 ```
208
209 You can remove both Subcollection and ArvadosFile.
210 If subcollection contains more files or folders they will be removed recursively.
211
212 You can also remove multiple files at once:
213
214 ```{r}
215 collection$remove(c("path/to/my/file.cpp", "path/to/other/file.cpp"))
216 ```
217
218 * Delete file or folder from a Subcollection:
219
220 ```{r}
221 subcollection <- collection$get("mySubcollection/")
222 subcollection$remove("fileInsideSubcollection.exe")
223 subcollection$remove("folderInsideSubcollection/")
224 ```
225
226 * Move or rename a file or folder within a collection (moving between collections is currently not supported):
227
228 Directly from collection
229
230 ```{r}
231 collection$move("folder/file.cpp", "file.cpp")
232 ```
233
234 Or from file
235
236 ```{r}
237 file <- collection$get("location/to/my/file.cpp")
238 file$move("newDestination/file.cpp")
239 ```
240
241 Or from subcollection
242
243 ```{r}
244 subcollection <- collection$get("location/to/folder")
245 subcollection$move("newDestination/folder")
246 ```
247
248 Make sure to include new file name in destination.
249 In second example file$move("newDestination/") will not work.
250
251 * Copy file or folder within a collection (copying between collections is currently not supported):
252
253 Directly from collection
254
255 ```{r}
256 collection$copy("folder/file.cpp", "file.cpp")
257 ```
258
259 Or from file
260
261 ```{r}
262 file <- collection$get("location/to/my/file.cpp")
263 file$copy("destination/file.cpp")
264 ```
265
266 Or from subcollection
267
268 ```{r}
269 subcollection <- collection$get("location/to/folder")
270 subcollection$copy("destination/folder")
271 ```
272
273 #### Working with Aravdos projects
274
275 * Get a project:
276
277 ```{r}
278 project <- arv$projects.get("uuid")
279 ```
280
281 * List projects:
282
283 ```{r}
284 list subprojects of a project
285 projects <- arv$projects.list(list(list("owner_uuid", "=", "aaaaa-j7d0g-ccccccccccccccc")))
286
287 list projects which have names beginning with Example
288 examples <- arv$projects.list(list(list("name","like","Example%")))
289 ```
290
291 * List all projects even if the number of items is greater than maximum API limit:
292
293 ```{r}
294 projects <- listAll(arv$projects.list, list(list("name","like","Example%")))
295 ```
296
297 * Delete a project:
298
299 ```{r}
300 deletedProject <- arv$projects.delete("uuid")
301 ```
302
303 * Update project:
304
305 ```{r}
306 updatedProject <- arv$projects.update(list(name = "new_name", description = "new description"), "uuid")
307 ```
308
309 * Create project:
310
311 ```{r}
312 newProject <- arv$projects.update(list(name = "project_name", description = "project description"))
313 ```
314
315 #### Help
316
317 * View help page of Arvados classes by puting ? before class name:
318
319 ```{r}
320 ?Arvados
321 ?Collection
322 ?Subcollection
323 ?ArvadosFile
324 ```
325
326 * View help page of any method defined in Arvados class by puting ? before method name:
327
328 ```{r}
329 ?collections.update
330 ?jobs.get
331 ```
332
333 ### Building the ArvadosR package
334
335 ```{bash}
336 cd arvados/sdk && R CMD build R
337 ```
338
339 This will create a tarball of the ArvadosR package in the current directory.