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
 184 #### Get ArvadosFile or Subcollection size:
 185
 186 ```r
 187 size <- arvadosFile$getSizeInBytes()
 188 # or
 189 size <- arvadosSubcollection$getSizeInBytes()
 190 ```
 191
 192 #### Create new file in a collection (returns a vector of one or more ArvadosFile objects):
 193
 194 ```r
 195 collection$create(files)
 196 ```
 197
 198 **Example**
 199
 200 ```
 201 mainFile <- collection$create("cpp/src/main.cpp")[[1]]
 202 fileList <- collection$create(c("cpp/src/main.cpp", "cpp/src/util.h"))
 203 ```
 204
 205 #### Delete file from a collection:
 206
 207 ```r
 208 collection$remove("location/to/my/file.cpp")
 209 ```
 210
 211 You can remove both Subcollection and ArvadosFile. If subcollection contains more files or folders they will be removed recursively.
 212
 213 > **Note**
 214 > You can also remove multiple files at once:
 215 > ```
 216 > collection$remove(c("path/to/my/file.cpp", "path/to/other/file.cpp"))
 217 > ```
 218
 219 #### Delete file or folder from a Subcollection:
 220
 221 ```r
 222 subcollection <- collection$get("mySubcollection/")
 223 subcollection$remove("fileInsideSubcollection.exe")
 224 subcollection$remove("folderInsideSubcollection/")
 225 ```
 226
 227 #### Move or rename a file or folder within a collection (moving between collections is currently not supported):
 228
 229 ##### Directly from collection
 230
 231 ```r
 232 collection$move("folder/file.cpp", "file.cpp")
 233 ```
 234
 235 ##### Or from file
 236
 237 ```r
 238 file <- collection$get("location/to/my/file.cpp")
 239 file$move("newDestination/file.cpp")
 240 ```
 241
 242 ##### Or from subcollection
 243
 244 ```r
 245 subcollection <- collection$get("location/to/folder")
 246 subcollection$move("newDestination/folder")
 247 ```
 248
 249 > **Note**
 250 > Make sure to include new file name in destination. In second example `file$move(“newDestination/”)` will not work.
 251
 252 #### Copy file or folder within a collection (copying between collections is currently not supported):
 253
 254 ##### Directly from collection
 255
 256 ```r
 257 collection$copy("folder/file.cpp", "file.cpp")
 258 ```
 259
 260 ##### Or from file
 261
 262 ```r
 263 file <- collection$get("location/to/my/file.cpp")
 264 file$copy("destination/file.cpp")
 265 ```
 266
 267 ##### Or from subcollection
 268
 269 ```r
 270 subcollection <- collection$get("location/to/folder")
 271 subcollection$copy("destination/folder")
 272 ```
 273
 274 ### Working with Aravdos projects
 275
 276 #### Get a project:
 277
 278 ```r
 279 project <- arv$project_get("uuid")
 280 ```
 281
 282 #### List projects:
 283
 284 ```r
 285 list subprojects of a project
 286 projects <- arv$project_list(list(list("owner_uuid", "=", "aaaaa-j7d0g-ccccccccccccccc")))
 287
 288 list projects which have names beginning with Example
 289 examples <- arv$project_list(list(list("name","like","Example%")))
 290 ```
 291
 292 #### List all projects even if the number of items is greater than maximum API limit:
 293
 294 ```r
 295 projects <- listAll(arv$project_list, list(list("name","like","Example%")))
 296 ```
 297
 298 ##### Delete a project:
 299
 300 ```r
 301 deletedProject <- arv$project_delete("uuid")
 302 ```
 303
 304 ##### Update project:
 305
 306 ```r
 307 updatedProject <- arv$project_update(name = "new project name", properties = newProperties, uuid = "projectUUID")
 308 ```
 309
 310 ##### Create project:
 311
 312 ```r
 313 newProject <- arv$project_create(name = "project name", description = "project description", owner_uuid = "project UUID", properties = NULL, ensureUniqueName = "false")
 314 ```
 315
 316 ### Help
 317
 318 #### View help page of Arvados classes by puting `?` before class name:
 319
 320 ```r
 321 ?Arvados
 322 ?Collection
 323 ?Subcollection
 324 ?ArvadosFile
 325 ```
 326
 327 #### View help page of any method defined in Arvados class by puting `?` before method name:
 328
 329 ```r
 330 ?collections_update
 331 ?jobs_get
 332 ```
 333
 334  <!-- Taka konwencja USAGE -->
 335
 336 ## Building the ArvadosR package
 337
 338 ```r
 339 cd arvados/sdk && R CMD build R
 340 ```
 341
 342 This will create a tarball of the ArvadosR package in the current directory.
 343
 344  <!-- Czy dodawać Documentation / Community / Development and Contributing / Licensing? Ale tylko do części Rowej? Wszystko? Wcale? -->
 345
 346 ## Documentation
 347
 348 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
 349 [API documentation](https://doc.arvados.org/api/index.html) is available at http://doc.arvados.org/
 350
 351 If you wish to build the Arvados documentation from a local git clone, see
 352 [doc/README.textile](doc/README.textile) for instructions.
 353
 354 ## Community
 355
 356 [![Join the chat at https://gitter.im/arvados/community](https://badges.gitter.im/arvados/community.svg)](https://gitter.im/arvados/community?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
 357
 358 The [Arvados community channel](https://gitter.im/arvados/community)
 359 channel at [gitter.im](https://gitter.im) is available for live
 360 discussion and support.
 361
 362 The [Arvados developement channel](https://gitter.im/arvados/development)
 363 channel at [gitter.im](https://gitter.im) is used to coordinate development.
 364
 365 The [Arvados user mailing list](http://lists.arvados.org/mailman/listinfo/arvados)
 366 is used to announce new versions and other news.
 367
 368 All participants are expected to abide by the [Arvados Code of Conduct](CODE_OF_CONDUCT.md).
 369
 370 ## Reporting bugs
 371
 372 [Report a bug](https://dev.arvados.org/projects/arvados/issues/new) on [dev.arvados.org](https://dev.arvados.org).
 373
 374 ## Development and Contributing
 375
 376 See [CONTRIBUTING](CONTRIBUTING.md) for information about Arvados development and how to contribute to the Arvados project.
 377
 378 The [development road map](https://dev.arvados.org/issues/gantt?utf8=%E2%9C%93&set_filter=1&gantt=1&f%5B%5D=project_id&op%5Bproject_id%5D=%3D&v%5Bproject_id%5D%5B%5D=49&f%5B%5D=&zoom=1) outlines some of the project priorities over the next twelve months.
 379
 380 ## Licensing
 381
 382 Arvados is Free Software.  See [COPYING](COPYING) for information about the open source licenses used in Arvados.