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