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.