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(files)
 190 ```
 191
 192 Example:
 193
 194 ```{r}
 195 mainFile <- collection$create("cpp/src/main.cpp")
 196 fileList <- collection$create(c("cpp/src/main.cpp", "cpp/src/util.h"))
 197 ```
 198
 199 * Delete file from a collection:
 200
 201 ```{r}
 202 collection$remove("location/to/my/file.cpp")
 203 ```
 204
 205 You can remove both Subcollection and ArvadosFile.
 206 If subcollection contains more files or folders they will be removed recursively.
 207
 208 You can also remove multiple files at once:
 209
 210 ```{r}
 211 collection$remove(c("path/to/my/file.cpp", "path/to/other/file.cpp"))
 212 ```
 213
 214 * Delete file or folder from a Subcollection:
 215
 216 ```{r}
 217 subcollection <- collection$get("mySubcollection/")
 218 subcollection$remove("fileInsideSubcollection.exe")
 219 subcollection$remove("folderInsideSubcollection/")
 220 ```
 221
 222 * Move or rename a file or folder within a collection (moving between collections is currently not supported):
 223
 224 Directly from collection
 225
 226 ```{r}
 227 collection$move("folder/file.cpp", "file.cpp")
 228 ```
 229
 230 Or from file
 231
 232 ```{r}
 233 file <- collection$get("location/to/my/file.cpp")
 234 file$move("newDestination/file.cpp")
 235 ```
 236
 237 Or from subcollection
 238
 239 ```{r}
 240 subcollection <- collection$get("location/to/folder")
 241 subcollection$move("newDestination/folder")
 242 ```
 243
 244 Make sure to include new file name in destination.
 245 In second example file$move("newDestination/") will not work.
 246
 247 * Copy file or folder within a collection (copying between collections is currently not supported):
 248
 249 Directly from collection
 250
 251 ```{r}
 252 collection$copy("folder/file.cpp", "file.cpp")
 253 ```
 254
 255 Or from file
 256
 257 ```{r}
 258 file <- collection$get("location/to/my/file.cpp")
 259 file$copy("destination/file.cpp")
 260 ```
 261
 262 Or from subcollection
 263
 264 ```{r}
 265 subcollection <- collection$get("location/to/folder")
 266 subcollection$copy("destination/folder")
 267 ```
 268
 269 #### Working with Aravdos projects
 270
 271 * Get a project:
 272
 273 ```{r}
 274 project <- arv$projects.get("uuid")
 275 ```
 276
 277 * List projects:
 278
 279 ```{r}
 280 list subprojects of a project
 281 projects <- arv$projects.list(list(list("owner_uuid", "=", "aaaaa-j7d0g-ccccccccccccccc")))
 282
 283 list projects which have names beginning with Example
 284 examples <- arv$projects.list(list(list("name","like","Example%")))
 285 ```
 286
 287 * List all projects even if the number of items is greater than maximum API limit:
 288
 289 ```{r}
 290 projects <- listAll(arv$projects.list, list(list("name","like","Example%")))
 291 ```
 292
 293 * Delete a project:
 294
 295 ```{r}
 296 deletedProject <- arv$projects.delete("uuid")
 297 ```
 298
 299 * Update project:
 300
 301 ```{r}
 302 updatedProject <- arv$projects.update(list(name = "new_name", description = "new description"), "uuid")
 303 ```
 304
 305 * Create project:
 306
 307 ```{r}
 308 newProject <- arv$projects.update(list(name = "project_name", description = "project description"))
 309 ```
 310
 311 #### Help
 312
 313 * View help page of Arvados classes by puting ? before class name:
 314
 315 ```{r}
 316 ?Arvados
 317 ?Collection
 318 ?Subcollection
 319 ?ArvadosFile
 320 ```
 321
 322 * View help page of any method defined in Arvados class by puting ? before method name:
 323
 324 ```{r}
 325 ?collections.update
 326 ?jobs.get
 327 ```
 328
 329 ### Building the ArvadosR package
 330
 331 ```{bash}
 332 cd arvados/sdk && R CMD build R
 333 ```
 334
 335 This will create a tarball of the ArvadosR package in the current directory.