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 1. Install the dependencies
   9
  10     `install.packages(c('R6', 'httr', 'stringr', 'jsonlite', 'curl', 'XML'))`
  11
  12     If needed, you may have to install the supporting packages first.
  13     On Linux, these are: libxml2-dev, libssl-dev, libcurl4-gnutls-dev or libcurl4-openssl-dev
  14
  15
  16 2. Install the ArvardosR package
  17
  18     `install.packages('/path/to/ArvadosR_0.0.2.tar.gz', repos = NULL, type="source", dependencies = TRUE)`
  19
  20 ### EXAMPLES OF USAGE
  21
  22 #### INITIALIZING API
  23
  24 * Load Library and Initialize API:
  25
  26     `library('ArvadosR')`
  27     `arv <- Arvados$new() # uses environment variables ARVADOS_API_TOKEN and ARVADOS_API_HOST`
  28     `arv <- Arvados$new("your Arvados token", "example.arvadosapi.com")`
  29
  30     Optionally, add numRetries parameter to specify number of times to retry failed service requests.
  31     Default is 0.
  32
  33     `arv <- Arvados$new("your Arvados token", "example.arvadosapi.com", numRetries = 3)`
  34
  35     This parameter can be set at any time using setNumRetries
  36
  37     `arv$setNumRetries(5)`
  38
  39
  40 #### WORKING WITH COLLECTIONS
  41
  42 * Get a collection:
  43
  44     `collection <- arv$getCollection("uuid")`
  45
  46 * List collections:
  47
  48     `collectionList <- arv$listCollections(list(list("name", "like", "Test%"))) # offset of 0 and default limit of 100`
  49     `collectionList <- arv$listCollections(list(list("name", "like", "Test%")), limit = 10, offset = 2)`
  50
  51     `collectionList$items_available # count of total number of items (may be more than returned due to paging)`
  52     `collectionList$items # items which match the filter criteria`
  53
  54 * List all collections even when the number of items is greater than maximum API limit:
  55
  56     `collectionList <- arv$listAllCollections(list(list("name", "like", "Test%")))`
  57
  58 * Delete a collection:
  59
  60     `deletedCollection <- arv$deleteCollection("uuid")`
  61
  62 * Update a collection's metadata:
  63
  64     `updatedCollection <- arv$updateCollection("uuid", list(name = "New name", description = "New description"))`
  65
  66 * Create collection:
  67
  68     `createdCollection <- arv$createCollection(list(name = "Example", description = "This is a test collection"))`
  69
  70
  71 #### MANIPULATIN COLLECTION CONTENT
  72
  73 * Create collection object:
  74
  75     `collection <- Collection$new(arv, "uuid")`
  76
  77 * Get list of files:
  78
  79     `files <- collection$getFileListing()`
  80
  81 * Get ArvadosFile or Subcollection from internal tree-like structure:
  82
  83     `arvadosFile <- collection$get("location/to/my/file.cpp")`
  84
  85     or
  86
  87     `arvadosSubcollection <- collection$get("location/to/my/directory/")`
  88
  89 * Read a table:
  90
  91     `arvadosFile   <- collection$get("myinput.txt")`
  92     `arvConnection <- arvadosFile$connection("r")`
  93     `mytable       <- read.table(arvConnection)`
  94
  95 * Write a table:
  96
  97     `arvadosFile   <- collection$create("myoutput.txt")`
  98     `arvConnection <- arvadosFile$connection("w")`
  99     `write.table(mytable, arvConnection)`
 100     `arvadosFile$flush()`
 101
 102 * Read whole file or just a portion of it:
 103
 104     `fileContent <- arvadosFile$read()`
 105     `fileContent <- arvadosFile$read("text")`
 106     `fileContent <- arvadosFile$read("raw", offset = 1024, length = 512)`
 107
 108 * Get ArvadosFile or Subcollection size:
 109
 110     `size <- arvadosFile$getSizeInBytes()`
 111
 112     or
 113
 114     `size <- arvadosSubcollection$getSizeInBytes()`
 115
 116 * Create new file in a collection:
 117
 118     `collection$create(fileNames, optionalRelativePath)`
 119
 120     Example:
 121
 122     `mainFile <- collection$create("main.cpp", "cpp/src/")`
 123     `fileList <- collection$create(c("main.cpp", lib.dll), "cpp/src/")`
 124
 125 * Add existing ArvadosFile or Subcollection to a collection:
 126
 127     `folder <- Subcollection$new("src")`
 128     `file   <- ArvadosFile$new("main.cpp")`
 129     `folder$add(file)`
 130
 131     `collection$add(folder, "cpp")`
 132
 133     This examples will add file "main.cpp" in "./cpp/src/" folder if folder exists.
 134     If subcollection contains more files or folders they will be added recursively.
 135
 136 * Write to existing file (override current content of the file):
 137
 138     `arvadosFile <- collection$get("location/to/my/file.cpp")`
 139     `arvadosFile$write("This is new file content")`
 140
 141 * Delete file from a collection:
 142
 143     `collection$remove("location/to/my/file.cpp")`
 144
 145     You can remove both Subcollection and ArvadosFile.
 146     If subcollection contains more files or folders they will be removed recursively.
 147
 148     You can also remove multiple files at once:
 149
 150     `collection$remove(c("path/to/my/file.cpp", "path/to/other/file.cpp"))`
 151
 152 * Delete file or folder from a Subcollection:
 153
 154     `subcollection <- collection$get("mySubcollection/")`
 155     `subcollection$remove("fileInsideSubcollection.exe")`
 156     `subcollection$remove("folderInsideSubcollection/")`
 157
 158 * Move file or folder inside collection:
 159
 160     Directley from collection
 161
 162     `collection$move("folder/file.cpp", "file.cpp")`
 163
 164     Or from file
 165
 166     `file <- collection$get("location/to/my/file.cpp")`
 167     `file$move("newDestination/file.cpp")`
 168
 169     Or from subcollection
 170
 171     `subcollection <- collection$get("location/to/folder")`
 172     `subcollection$move("newDestination/folder")`
 173
 174     Make sure to include new file name in destination.
 175     In second example file$move("newDestination/") will not work.
 176
 177 #### WORKING WITH ARVADOS PROJECTS
 178
 179 * Get a project:
 180
 181     `project <- arv$getProject("uuid")`
 182
 183 * List projects:
 184
 185     `projects <- arv$listProjects(list(list("owner_uuid", "=", "aaaaa-j7d0g-ccccccccccccccc"))) # list subprojects of a project`
 186     `arv$listProjects(list(list("name","like","Example%"))) # list projects which have names beginning with Example`
 187
 188 * List all projects even when the number of items is greater than maximum API limit:
 189
 190     `collectionList <- arv$listAllProjects(list(list("name","like","Example%")))`
 191
 192 * Delete a project:
 193
 194     `deletedProject <- arv$deleteProject("uuid")`
 195
 196 * Update project:
 197
 198     `updatedProject <- arv$updateProject("uuid", list(name = "new_name", description = "new description"))`
 199
 200 * Create project:
 201
 202     `createdProject <- arv$createProject(list(name = "project_name", description = "project description"))`
 203
 204 ### BUILDING THE ARVADOS SDK TARBALL
 205
 206 cd arvados/sdk
 207 R CMD build R
 208
 209 This will create a tarball of the Arvados package in the current directory.