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