sdk/R/README

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