sdk/R/README.Rmd

   1 ## R SDK for Arvados
   2
   3 This SDK focuses on providing support for accessing Arvados projects, collections, and the files within collections.
   4 The API is not final and feedback is solicited from users on ways in which it could be improved.
   5
   6 ### Installation
   7
   8 ```{r include=FALSE}
   9 knitr::opts_chunk$set(eval=FALSE)
  10 ```
  11
  12 ```{r}
  13 install.packages("ArvadosR", repos=c("http://r.arvados.org", getOption("repos")["CRAN"]), dependencies=TRUE)
  14 ```
  15
  16 Note: on Linux, you may have to install supporting packages.
  17
  18 On Centos 7, this is:
  19
  20 ```{bash}
  21 yum install libxml2-devel openssl-devel curl-devel
  22 ```
  23
  24 On Debian, this is:
  25
  26 ```{bash}
  27 apt-get install build-essential libxml2-dev libssl-dev libcurl4-gnutls-dev
  28 ```
  29
  30
  31 ### Usage
  32
  33 #### Initializing API
  34
  35 * Load Library and Initialize API:
  36
  37 ```{r}
  38 library('ArvadosR')
  39 # use environment variables ARVADOS_API_TOKEN and ARVADOS_API_HOST
  40 arv <- Arvados$new()
  41
  42 # provide them explicitly
  43 arv <- Arvados$new("your Arvados token", "example.arvadosapi.com")
  44 ```
  45
  46 Optionally, add numRetries parameter to specify number of times to retry failed service requests.
  47 Default is 0.
  48
  49 ```{r}
  50 arv <- Arvados$new("your Arvados token", "example.arvadosapi.com", numRetries = 3)
  51 ```
  52
  53 This parameter can be set at any time using setNumRetries
  54
  55 ```{r}
  56 arv$setNumRetries(5)
  57 ```
  58
  59
  60 #### Working with collections
  61
  62 * Get a collection:
  63
  64 ```{r}
  65 collection <- arv$collections.get("uuid")
  66 ```
  67
  68 * List collections:
  69
  70 ```{r}
  71 # offset of 0 and default limit of 100
  72 collectionList <- arv$collections.list(list(list("name", "like", "Test%")))
  73
  74 collectionList <- arv$collections.list(list(list("name", "like", "Test%")), limit = 10, offset = 2)
  75 ```
  76
  77 ```{r}
  78 # count of total number of items (may be more than returned due to paging)
  79 collectionList$items_available
  80
  81 # items which match the filter criteria
  82 collectionList$items
  83 ```
  84
  85 * List all collections even if the number of items is greater than maximum API limit:
  86
  87 ```{r}
  88 collectionList <- listAll(arv$collections.list, list(list("name", "like", "Test%")))
  89 ```
  90
  91 * Delete a collection:
  92
  93 ```{r}
  94 deletedCollection <- arv$collections.delete("uuid")
  95 ```
  96
  97 * Update a collection's metadata:
  98
  99 ```{r}
 100 updatedCollection <- arv$collections.update(list(name = "New name", description = "New description"), "uuid")
 101 ```
 102
 103 * Create collection:
 104
 105 ```{r}
 106 newCollection <- arv$collections.create(list(name = "Example", description = "This is a test collection"))
 107 ```
 108
 109
 110 #### Manipulating collection content
 111
 112 * Create collection object:
 113
 114 ```{r}
 115 collection <- Collection$new(arv, "uuid")
 116 ```
 117
 118 * Get list of files:
 119
 120 ```{r}
 121 files <- collection$getFileListing()
 122 ```
 123
 124 * Get ArvadosFile or Subcollection from internal tree-like structure:
 125
 126 ```{r}
 127 arvadosFile <- collection$get("location/to/my/file.cpp")
 128 ```
 129
 130     or
 131
 132 ```{r}
 133 arvadosSubcollection <- collection$get("location/to/my/directory/")
 134 ```
 135
 136 * Read a table:
 137
 138 ```{r}
 139 arvadosFile   <- collection$get("myinput.txt")
 140 arvConnection <- arvadosFile$connection("r")
 141 mytable       <- read.table(arvConnection)
 142 ```
 143
 144 * Write a table:
 145
 146 ```{r}
 147 arvadosFile   <- collection$create("myoutput.txt")
 148 arvConnection <- arvadosFile$connection("w")
 149 write.table(mytable, arvConnection)
 150 arvadosFile$flush()
 151 ```
 152
 153 * Write to existing file (override current content of the file):
 154
 155 ```{r}
 156 arvadosFile <- collection$get("location/to/my/file.cpp")
 157 arvadosFile$write("This is new file content")
 158 ```
 159
 160 * Read whole file or just a portion of it:
 161
 162 ```{r}
 163 fileContent <- arvadosFile$read()
 164 fileContent <- arvadosFile$read("text")
 165 fileContent <- arvadosFile$read("raw", offset = 1024, length = 512)
 166 ```
 167
 168 * Get ArvadosFile or Subcollection size:
 169
 170 ```{r}
 171 size <- arvadosFile$getSizeInBytes()
 172 ```
 173
 174     or
 175
 176 ```{r}
 177 size <- arvadosSubcollection$getSizeInBytes()
 178 ```
 179
 180 * Create new file in a collection:
 181
 182 ```{r}
 183 collection$create(fileNames, optionalRelativePath)
 184 ```
 185
 186     Example:
 187
 188 ```{r}
 189 mainFile <- collection$create("main.cpp", "cpp/src/")
 190 fileList <- collection$create(c("main.cpp", lib.dll), "cpp/src/")
 191 ```
 192
 193 * Add existing ArvadosFile or Subcollection to a collection:
 194
 195 ```{r}
 196 folder <- Subcollection$new("src")
 197 file   <- ArvadosFile$new("main.cpp")
 198 folder$add(file)
 199 ```
 200
 201 ```{r}
 202 collection$add(folder, "cpp")
 203 ```
 204
 205 This examples will add file "main.cpp" in "./cpp/src/" folder if folder exists.
 206 If subcollection contains more files or folders they will be added recursively.
 207
 208 * Delete file from a collection:
 209
 210 ```{r}
 211 collection$remove("location/to/my/file.cpp")
 212 ```
 213
 214 You can remove both Subcollection and ArvadosFile.
 215 If subcollection contains more files or folders they will be removed recursively.
 216
 217 You can also remove multiple files at once:
 218
 219 ```{r}
 220 collection$remove(c("path/to/my/file.cpp", "path/to/other/file.cpp"))
 221 ```
 222
 223 * Delete file or folder from a Subcollection:
 224
 225 ```{r}
 226 subcollection <- collection$get("mySubcollection/")
 227 subcollection$remove("fileInsideSubcollection.exe")
 228 subcollection$remove("folderInsideSubcollection/")
 229 ```
 230
 231 * Move file or folder inside collection:
 232
 233 Directley from collection
 234
 235 ```{r}
 236 collection$move("folder/file.cpp", "file.cpp")
 237 ```
 238
 239 Or from file
 240
 241 ```{r}
 242 file <- collection$get("location/to/my/file.cpp")
 243 file$move("newDestination/file.cpp")
 244 ```
 245
 246 Or from subcollection
 247
 248 ```{r}
 249 subcollection <- collection$get("location/to/folder")
 250 subcollection$move("newDestination/folder")
 251 ```
 252
 253 Make sure to include new file name in destination.
 254 In second example file$move("newDestination/") will not work.
 255
 256 #### Working with Aravdos projects
 257
 258 * Get a project:
 259
 260 ```{r}
 261 project <- arv$projects.get("uuid")
 262 ```
 263
 264 * List projects:
 265
 266 ```{r}
 267 list subprojects of a project
 268 projects <- arv$projects.list(list(list("owner_uuid", "=", "aaaaa-j7d0g-ccccccccccccccc")))
 269
 270 list projects which have names beginning with Example
 271 examples <- arv$projects.list(list(list("name","like","Example%")))
 272 ```
 273
 274 * List all projects even if the number of items is greater than maximum API limit:
 275
 276 ```{r}
 277 projects <- listAll(arv$projects.list, list(list("name","like","Example%")))
 278 ```
 279
 280 * Delete a project:
 281
 282 ```{r}
 283 deletedProject <- arv$projects.delete("uuid")
 284 ```
 285
 286 * Update project:
 287
 288 ```{r}
 289 updatedProject <- arv$projects.update(list(name = "new_name", description = "new description"), "uuid")
 290 ```
 291
 292 * Create project:
 293
 294 ```{r}
 295 newProject <- arv$projects.update(list(name = "project_name", description = "project description"))
 296 ```
 297
 298 #### Help
 299
 300 * View help page of Arvados classes by puting ? before class name:
 301
 302 ```{r}
 303 ?Arvados
 304 ?Collection
 305 ?Subcollection
 306 ?ArvadosFile
 307 ```
 308
 309 * View help page of any method defined in Arvados class by puting ? before method name:
 310
 311 ```{r}
 312 ?collections.update
 313 ?jobs.get
 314 ```
 315
 316 ### Building the ArvadosR package
 317
 318 ```{bash}
 319 cd arvados/sdk && R CMD build R
 320 ```
 321
 322 This will create a tarball of the ArvadosR package in the current directory.