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 Red Hat, AlmaLinux, and Rocky Linux, this is:
  32 > ```
  33 > yum install libxml2-devel openssl-devel curl-devel
  34 > ```
  35 >
  36 > On Debian and Ubuntu, 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 Aravdos projects
  67
  68 ##### Create project:
  69
  70 ```r
  71 newProject <- arv$project_create(name = "project name", description = "project description", owner_uuid = "project UUID", properties = NULL, ensureUniqueName = "false")
  72 ```
  73
  74 ##### Update project:
  75
  76 ```r
  77 updatedProject <- arv$project_update(name = "new project name", properties = newProperties, uuid = "projectUUID")
  78 ```
  79
  80 ##### Delete a project:
  81
  82 ```r
  83 deletedProject <- arv$project_delete("uuid")
  84 ```
  85
  86 #### Find a project:
  87
  88 ##### Get a project:
  89
  90 ```r
  91 project <- arv$project_get("uuid")
  92 ```
  93
  94 ##### List projects:
  95
  96 ```r
  97 list subprojects of a project
  98 projects <- arv$project_list(list(list("owner_uuid", "=", "aaaaa-j7d0g-ccccccccccccccc")))
  99
 100 list projects which have names beginning with Example
 101 examples <- arv$project_list(list(list("name","like","Example%")))
 102 ```
 103
 104 ##### List all projects even if the number of items is greater than maximum API limit:
 105
 106 ```r
 107 projects <- listAll(arv$project_list, list(list("name","like","Example%")))
 108 ```
 109
 110 ### Working with collections
 111
 112 #### Create a new collection:
 113
 114 ```r
 115 newCollection <- arv$collections_create(name = "collectionTitle", description = "collectionDescription", ownerUUID = "collectionOwner", properties = Properties)
 116 ```
 117
 118 #### Update a collection’s metadata:
 119
 120 ```r
 121 collection <- arv$collections_update(name = "newCollectionTitle", description = "newCollectionDescription", ownerUUID = "collectionOwner", properties = NULL, uuid =  "collectionUUID")
 122 ```
 123
 124 #### Delete a collection:
 125
 126 ```r
 127 deletedCollection <- arv$collections_delete("uuid")
 128 ```
 129
 130 #### Find a collection:
 131
 132 #### Get a collection:
 133
 134 ```r
 135 collection <- arv$collections_get("uuid")
 136 ```
 137
 138 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.
 139
 140 #### List collections:
 141
 142 ```r
 143 # offset of 0 and default limit of 100
 144 collectionList <- arv$collections_list(list(list("name", "like", "Test%")))
 145
 146 collectionList <- arv$collections_list(list(list("name", "like", "Test%")), limit = 10, offset = 2)
 147
 148 # count of total number of items (may be more than returned due to paging)
 149 collectionList$items_available
 150
 151 # items which match the filter criteria
 152 collectionList$items
 153 ```
 154
 155 #### List all collections even if the number of items is greater than maximum API limit:
 156
 157 ```r
 158 collectionList <- listAll(arv$collections_list, list(list("name", "like", "Test%")))
 159 ```
 160
 161 ### Manipulating collection content
 162
 163 #### Initialize a collection object:
 164
 165 ```r
 166 collection <- Collection$new(arv, "uuid")
 167 ```
 168
 169 #### Get list of files:
 170
 171 ```r
 172 files <- collection$getFileListing()
 173 ```
 174
 175 #### Get ArvadosFile or Subcollection from internal tree-like structure:
 176
 177 ```r
 178 arvadosFile <- collection$get("location/to/my/file.cpp")
 179 # or
 180 arvadosSubcollection <- collection$get("location/to/my/directory/")
 181 ```
 182
 183 #### Read a table:
 184
 185 ```r
 186 arvadosFile   <- collection$get("myinput.txt")
 187 arvConnection <- arvadosFile$connection("r")
 188 mytable       <- read.table(arvConnection)
 189 ```
 190
 191 #### Write a table:
 192
 193 ```r
 194 arvadosFile   <- collection$create("myoutput.txt")[[1]]
 195 arvConnection <- arvadosFile$connection("w")
 196 write.table(mytable, arvConnection)
 197 arvadosFile$flush()
 198 ```
 199
 200 #### Read a table from a tab delimited file:
 201
 202 ```r
 203 arvadosFile   <- collection$get("myinput.txt")
 204 arvConnection <- arvadosFile$connection("r")
 205 mytable       <- read.delim(arvConnection)
 206 ```
 207
 208 #### Read a gzip compressed R object:
 209
 210 ```r
 211 obj <- readRDS(gzcon(coll$get("abc.RDS")$connection("rb")))
 212 ```
 213
 214 #### Write to existing file (overwrites current content of the file):
 215
 216 ```r
 217 arvadosFile <- collection$get("location/to/my/file.cpp")
 218 arvadosFile$write("This is new file content")
 219 ```
 220
 221 #### Read whole file or just a portion of it:
 222
 223 ```r
 224 fileContent <- arvadosFile$read()
 225 fileContent <- arvadosFile$read("text")
 226 fileContent <- arvadosFile$read("raw", offset = 1024, length = 512)
 227 ```
 228
 229 #### Read various file types:
 230
 231 Chooses file type based on file name extension.  Recognized file extensions: 'txt', 'xlsx', 'csv', 'tsv', 'fasta', 'dat', 'bin', 'rds', 'rdata'.
 232
 233 ```r
 234 collection <- Collection$new(arv, collectionUUID)
 235 readFile <- collection$readArvFile(arvadosFile, istable = 'yes')                    # table
 236 readFile <- collection$readArvFile(arvadosFile, istable = 'no')                     # text
 237 readFile <- collection$readArvFile(arvadosFile)                                     # xlsx, csv, tsv, rds, rdata
 238 readFile <- collection$readArvFile(arvadosFile, fileclass = 'fasta')                # fasta
 239 readFile <- collection$readArvFile(arvadosFile, Ncol= 4, Nrow = 32)                 # binary data.frame, only numbers
 240 readFile <- collection$readArvFile(arvadosFile, Ncol = 5, Nrow = 150, istable = "factor") # binary data.frame with factor or text
 241 ```
 242
 243 #### Get ArvadosFile or Subcollection size:
 244
 245 ```r
 246 size <- arvadosFile$getSizeInBytes()
 247 # or
 248 size <- arvadosSubcollection$getSizeInBytes()
 249 ```
 250
 251 #### Create new file in a collection (returns a vector of one or more ArvadosFile objects):
 252
 253 ```r
 254 collection$create(files)
 255 ```
 256
 257 **Example**
 258
 259 ```
 260 mainFile <- collection$create("cpp/src/main.cpp")[[1]]
 261 fileList <- collection$create(c("cpp/src/main.cpp", "cpp/src/util.h"))
 262 ```
 263
 264 #### Delete file from a collection:
 265
 266 ```r
 267 collection$remove("location/to/my/file.cpp")
 268 ```
 269
 270 You can remove both Subcollection and ArvadosFile. If subcollection contains more files or folders they will be removed recursively.
 271
 272 > **Note**
 273 > You can also remove multiple files at once:
 274 > ```
 275 > collection$remove(c("path/to/my/file.cpp", "path/to/other/file.cpp"))
 276 > ```
 277
 278 #### Delete file or folder from a Subcollection:
 279
 280 ```r
 281 subcollection <- collection$get("mySubcollection/")
 282 subcollection$remove("fileInsideSubcollection.exe")
 283 subcollection$remove("folderInsideSubcollection/")
 284 ```
 285
 286 #### Move or rename a file or folder within a collection (moving between collections is currently not supported):
 287
 288 ##### Directly from collection
 289
 290 ```r
 291 collection$move("folder/file.cpp", "file.cpp")
 292 ```
 293
 294 ##### Or from file
 295
 296 ```r
 297 file <- collection$get("location/to/my/file.cpp")
 298 file$move("newDestination/file.cpp")
 299 ```
 300
 301 ##### Or from subcollection
 302
 303 ```r
 304 subcollection <- collection$get("location/to/folder")
 305 subcollection$move("newDestination/folder")
 306 ```
 307
 308 > **Note**
 309 > Make sure to include new file name in destination. In second example `file$move(“newDestination/”)` will not work.
 310
 311 #### Copy file or folder within a collection (copying between collections is currently not supported):
 312
 313 ##### Directly from collection
 314
 315 ```r
 316 collection$copy("folder/file.cpp", "file.cpp")
 317 ```
 318
 319 ##### Or from file
 320
 321 ```r
 322 file <- collection$get("location/to/my/file.cpp")
 323 file$copy("destination/file.cpp")
 324 ```
 325
 326 ##### Or from subcollection
 327
 328 ```r
 329 subcollection <- collection$get("location/to/folder")
 330 subcollection$copy("destination/folder")
 331 ```
 332
 333
 334 ### Help
 335
 336 #### View help page of Arvados classes by puting `?` before class name:
 337
 338 ```r
 339 ?Arvados
 340 ?Collection
 341 ?Subcollection
 342 ?ArvadosFile
 343 ```
 344
 345 #### View help page of any method defined in Arvados class by puting `?` before method name:
 346
 347 ```r
 348 ?collections_update
 349 ?workflows_get
 350 ```
 351
 352  <!-- Taka konwencja USAGE -->
 353
 354 ## Building the ArvadosR package
 355
 356 ```r
 357 cd arvados/sdk && R CMD build R
 358 ```
 359
 360 This will create a tarball of the ArvadosR package in the current directory.
 361
 362  <!-- Czy dodawać Documentation / Community / Development and Contributing / Licensing? Ale tylko do części Rowej? Wszystko? Wcale? -->
 363
 364 ## Documentation
 365
 366 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
 367 [API documentation](https://doc.arvados.org/api/index.html) is available at http://doc.arvados.org/
 368
 369 ## Community
 370
 371 Visit [Arvados Community and Getting Help](https://doc.arvados.org/user/getting_started/community.html).
 372
 373 ## Reporting bugs
 374
 375 [Report a bug](https://dev.arvados.org/projects/arvados/issues/new) on [dev.arvados.org](https://dev.arvados.org).
 376
 377 ## Licensing
 378
 379 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.