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