sdk/R/README.md

   1 [comment]: # (Copyright © 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. The API is not final and feedback is solicited from users on ways in which it could be improved.
   8
   9 ## Key Topics
  10 * Installation
  11 * Usage
  12   * Initializing API
  13   * Working with collections
  14   * Manipulating collection content
  15   * Working with Arvados projects
  16   * Help
  17 * Building the ArvadosR package
  18
  19 ## Installation
  20
  21 Minimum R version required to run ArvadosR is 3.3.0.
  22
  23 ```r
  24 install.packages("ArvadosR", repos=c("https://r.arvados.org", getOption("repos")["CRAN"]), dependencies=TRUE)
  25 library('ArvadosR')
  26 ```
  27
  28 > **Note**
  29 > On Linux, you may have to install supporting packages.
  30 >
  31 > On Centos 7, this is:
  32 > ```
  33 > yum install libxml2-devel openssl-devel curl-devel
  34 > ```
  35 >
  36 > On Debian, this is:
  37 > ```
  38 > apt-get install build-essential libxml2-dev libssl-dev libcurl4-gnutls-dev
  39 > ```
  40
  41
  42 ## Usage
  43
  44 ### Initializing API
  45
  46 ```r
  47 # use environment variables ARVADOS_API_TOKEN and ARVADOS_API_HOST
  48 arv <- Arvados$new()
  49
  50 # provide them explicitly
  51 arv <- Arvados$new("your Arvados token", "example.arvadosapi.com")
  52 ```
  53
  54 Optionally, add `numRetries` parameter to specify number of times to retry failed service requests. Default is 0.
  55
  56 ```r
  57 arv <- Arvados$new("your Arvados token", "example.arvadosapi.com", numRetries = 3)
  58 ```
  59
  60 This parameter can be set at any time using `setNumRetries`
  61
  62 ```r
  63 arv$setNumRetries(5)
  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 Collection class. The object returned from this method lets you access collection fields like “name” and “description”. The Collection class lets you access the files in the collection for reading and writing, and is described in the next section.
  75
  76 #### List collections:
  77
  78 ```r
  79 # offset of 0 and default limit of 100
  80 collectionList <- arv$collections_list(list(list("name", "like", "Test%")))
  81
  82 collectionList <- arv$collections_list(list(list("name", "like", "Test%")), limit = 10, offset = 2)
  83
  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 collection <- arv$collections_update(name = "newCollectionTitle", description = "newCollectionDescription", ownerUUID = "collectionOwner", properties = NULL, uuid =  "collectionUUID")
 107 ```
 108
 109 #### Create a new collection:
 110
 111 ```r
 112 newCollection <- arv$collections_create(name = "collectionTitle", description = "collectionDescription", ownerUUID = "collectionOwner", properties = Properties)
 113 ```
 114
 115 ### Manipulating collection content
 116
 117 #### Initialize a collection object:
 118
 119 ```r
 120 collection <- Collection$new(arv, "uuid")
 121 ```
 122
 123 #### Get list of files:
 124
 125 ```r
 126 files <- collection$getFileListing()
 127 ```
 128
 129 #### Get ArvadosFile or Subcollection from internal tree-like structure:
 130
 131 ```r
 132 arvadosFile <- collection$get("location/to/my/file.cpp")
 133 # or
 134 arvadosSubcollection <- collection$get("location/to/my/directory/")
 135 ```
 136
 137 #### Read a table:
 138
 139 ```r
 140 arvadosFile   <- collection$get("myinput.txt")
 141 arvConnection <- arvadosFile$connection("r")
 142 mytable       <- read.table(arvConnection)
 143 ```
 144
 145 #### Write a table:
 146
 147 ```r
 148 arvadosFile   <- collection$create("myoutput.txt")[[1]]
 149 arvConnection <- arvadosFile$connection("w")
 150 write.table(mytable, arvConnection)
 151 arvadosFile$flush()
 152 ```
 153
 154 #### Read a table from a tab delimited file:
 155
 156 ```r
 157 arvadosFile   <- collection$get("myinput.txt")
 158 arvConnection <- arvadosFile$connection("r")
 159 mytable       <- read.delim(arvConnection)
 160 ```
 161
 162 #### Read a gzip compressed R object:
 163
 164 ```r
 165 obj <- readRDS(gzcon(coll$get("abc.RDS")$connection("rb")))
 166 ```
 167
 168 #### Write to existing file (overwrites current content of the file):
 169
 170 ```r
 171 arvadosFile <- collection$get("location/to/my/file.cpp")
 172 arvadosFile$write("This is new file content")
 173 ```
 174
 175 #### Read whole file or just a portion of it:
 176
 177 ```r
 178 fileContent <- arvadosFile$read()
 179 fileContent <- arvadosFile$read("text")
 180 fileContent <- arvadosFile$read("raw", offset = 1024, length = 512)
 181 ```
 182
 183 #### Read various file types:
 184
 185 Chooses file type based on file name extension.  Recognized file extensions: 'txt', 'xlsx', 'csv', 'tsv', 'fasta', 'dat', 'bin', 'rds', 'rdata'.
 186
 187 ```r
 188 collection <- Collection$new(arv, collectionUUID)
 189 readFile <- collection$readArvFile(arvadosFile, istable = 'yes')                    # table
 190 readFile <- collection$readArvFile(arvadosFile, istable = 'no')                     # text
 191 readFile <- collection$readArvFile(arvadosFile)                                     # xlsx, csv, tsv, rds, rdata
 192 readFile <- collection$readArvFile(arvadosFile, fileclass = 'fasta')                # fasta
 193 readFile <- collection$readArvFile(arvadosFile, Ncol= 4, Nrow = 32)                 # binary data.frame, only numbers
 194 readFile <- collection$readArvFile(arvadosFile, Ncol = 5, Nrow = 150, istable = "factor") # binary data.frame with factor or text
 195 ```
 196
 197 #### Get ArvadosFile or Subcollection size:
 198
 199 ```r
 200 size <- arvadosFile$getSizeInBytes()
 201 # or
 202 size <- arvadosSubcollection$getSizeInBytes()
 203 ```
 204
 205 #### Create new file in a collection (returns a vector of one or more ArvadosFile objects):
 206
 207 ```r
 208 collection$create(files)
 209 ```
 210
 211 **Example**
 212
 213 ```
 214 mainFile <- collection$create("cpp/src/main.cpp")[[1]]
 215 fileList <- collection$create(c("cpp/src/main.cpp", "cpp/src/util.h"))
 216 ```
 217
 218 #### Delete file from a collection:
 219
 220 ```r
 221 collection$remove("location/to/my/file.cpp")
 222 ```
 223
 224 You can remove both Subcollection and ArvadosFile. If subcollection contains more files or folders they will be removed recursively.
 225
 226 > **Note**
 227 > You can also remove multiple files at once:
 228 > ```
 229 > collection$remove(c("path/to/my/file.cpp", "path/to/other/file.cpp"))
 230 > ```
 231
 232 #### Delete file or folder from a Subcollection:
 233
 234 ```r
 235 subcollection <- collection$get("mySubcollection/")
 236 subcollection$remove("fileInsideSubcollection.exe")
 237 subcollection$remove("folderInsideSubcollection/")
 238 ```
 239
 240 #### Move or rename a file or folder within a collection (moving between collections is currently not supported):
 241
 242 ##### Directly from collection
 243
 244 ```r
 245 collection$move("folder/file.cpp", "file.cpp")
 246 ```
 247
 248 ##### Or from file
 249
 250 ```r
 251 file <- collection$get("location/to/my/file.cpp")
 252 file$move("newDestination/file.cpp")
 253 ```
 254
 255 ##### Or from subcollection
 256
 257 ```r
 258 subcollection <- collection$get("location/to/folder")
 259 subcollection$move("newDestination/folder")
 260 ```
 261
 262 > **Note**
 263 > Make sure to include new file name in destination. In second example `file$move(“newDestination/”)` will not work.
 264
 265 #### Copy file or folder within a collection (copying between collections is currently not supported):
 266
 267 ##### Directly from collection
 268
 269 ```r
 270 collection$copy("folder/file.cpp", "file.cpp")
 271 ```
 272
 273 ##### Or from file
 274
 275 ```r
 276 file <- collection$get("location/to/my/file.cpp")
 277 file$copy("destination/file.cpp")
 278 ```
 279
 280 ##### Or from subcollection
 281
 282 ```r
 283 subcollection <- collection$get("location/to/folder")
 284 subcollection$copy("destination/folder")
 285 ```
 286
 287 ### Working with Aravdos projects
 288
 289 #### Get a project:
 290
 291 ```r
 292 project <- arv$project_get("uuid")
 293 ```
 294
 295 #### List projects:
 296
 297 ```r
 298 list subprojects of a project
 299 projects <- arv$project_list(list(list("owner_uuid", "=", "aaaaa-j7d0g-ccccccccccccccc")))
 300
 301 list projects which have names beginning with Example
 302 examples <- arv$project_list(list(list("name","like","Example%")))
 303 ```
 304
 305 #### List all projects even if the number of items is greater than maximum API limit:
 306
 307 ```r
 308 projects <- listAll(arv$project_list, list(list("name","like","Example%")))
 309 ```
 310
 311 ##### Delete a project:
 312
 313 ```r
 314 deletedProject <- arv$project_delete("uuid")
 315 ```
 316
 317 ##### Update project:
 318
 319 ```r
 320 updatedProject <- arv$project_update(name = "new project name", properties = newProperties, uuid = "projectUUID")
 321 ```
 322
 323 ##### Create project:
 324
 325 ```r
 326 newProject <- arv$project_create(name = "project name", description = "project description", owner_uuid = "project UUID", properties = NULL, ensureUniqueName = "false")
 327 ```
 328
 329 ### Help
 330
 331 #### View help page of Arvados classes by puting `?` before class name:
 332
 333 ```r
 334 ?Arvados
 335 ?Collection
 336 ?Subcollection
 337 ?ArvadosFile
 338 ```
 339
 340 #### View help page of any method defined in Arvados class by puting `?` before method name:
 341
 342 ```r
 343 ?collections_update
 344 ?jobs_get
 345 ```
 346
 347  <!-- Taka konwencja USAGE -->
 348
 349 ## Building the ArvadosR package
 350
 351 ```r
 352 cd arvados/sdk && R CMD build R
 353 ```
 354
 355 This will create a tarball of the ArvadosR package in the current directory.
 356
 357  <!-- Czy dodawać Documentation / Community / Development and Contributing / Licensing? Ale tylko do części Rowej? Wszystko? Wcale? -->
 358
 359 ## Documentation
 360
 361 Complete documentation, including the [User Guide](https://doc.arvados.org/user/index.html), [Installation documentation](https://doc.arvados.org/install/index.html), [Administrator documentation](https://doc.arvados.org/admin/index.html) and
 362 [API documentation](https://doc.arvados.org/api/index.html) is available at http://doc.arvados.org/
 363
 364 ## Community
 365
 366 Visit [Arvados Community and Getting Help](https://doc.arvados.org/user/getting_started/community.html).
 367
 368 ## Reporting bugs
 369
 370 [Report a bug](https://dev.arvados.org/projects/arvados/issues/new) on [dev.arvados.org](https://dev.arvados.org).
 371
 372 ## Licensing
 373
 374 Arvados is Free Software.  See [Arvados Free Software Licenses](https://doc.arvados.org/user/copying/copying.html) for information about the open source licenses used in Arvados.