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.