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.