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.1.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
  33 #Get a collection:
  34
  35 arv$getCollection("uuid")
  36
  37 --------------------------------------------------------------------------------------------------------------------------------
  38
  39 #List collections:
  40 collectionList <- arv$listCollections(list(list("name", "like", "Test%"))) # offset of 0 and default limit of 100
  41 collectionList <- arv$listCollections(list(list("name", "like", "Test%")), limit = 10, offset = 2)
  42
  43 collectionList$items_available # count of total number of items (may be more than returned due to paging)
  44 collectionList$items # items which match the filter criteria
  45
  46 --------------------------------------------------------------------------------------------------------------------------------
  47
  48 #Delete a collection:
  49
  50 deletedCollection <- arv$deleteCollection("uuid")
  51
  52 --------------------------------------------------------------------------------------------------------------------------------
  53
  54 #Update a collection's metadata:
  55
  56 updatedCollection <- arv$updateCollection("uuid", list(name = "My new name", description = "a brand new description"))
  57
  58 --------------------------------------------------------------------------------------------------------------------------------
  59
  60 #Create collection:
  61
  62 createdCollection <- arv$createCollection(list(name = "Example", description = "This is a test collection"))
  63
  64
  65 --------------------------------------------------------------------------------------------------------------------------------
  66 COLLECTION CONTENT MANIPULATION
  67 --------------------------------------------------------------------------------------------------------------------------------
  68
  69 #Create collection object:
  70
  71 collection <- Collection$new(arv, "uuid")
  72
  73 --------------------------------------------------------------------------------------------------------------------------------
  74
  75 #Get list of files
  76
  77 collection$getFileListing()
  78
  79 --------------------------------------------------------------------------------------------------------------------------------
  80
  81 #This will return 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 --------------------------------------------------------------------------------------------------------------------------------
  90
  91 #Read a table
  92
  93 arvadosFile <- collection$get("myinput.txt")
  94 arvConnection <- arvadosFile$connection("r")
  95 mytable <- read.table(arvConnection)
  96
  97 #Write a table
  98
  99 arvadosFile <- collection$create("myoutput.txt")
 100 arvConnection <- arvadosFile$connection("w")
 101 write.table(mytable, arvConnection)
 102 arvadosFile$flush()
 103
 104 --------------------------------------------------------------------------------------------------------------------------------
 105
 106 #Read whole file or just a portion of it.
 107
 108 fileContent <- arvadosFile$read()
 109 fileContent <- arvadosFile$read("text")
 110 fileContent <- arvadosFile$read("raw", offset = 1024, length = 512)
 111
 112 --------------------------------------------------------------------------------------------------------------------------------
 113
 114 #Get ArvadosFile or Subcollection size
 115
 116 size <- arvadosFile$getSizeInBytes()
 117 size <- arvadosSubcollection$getSizeInBytes()
 118
 119 --------------------------------------------------------------------------------------------------------------------------------
 120
 121 #Create new file in a collection
 122
 123 collection$create(fileNames, optionalRelativePath)
 124
 125 #Example
 126
 127 mainFile <- collection$create("main.cpp", "cpp/src/")
 128 fileList <- collection$create(c("main.cpp", lib.dll), "cpp/src/")
 129
 130 --------------------------------------------------------------------------------------------------------------------------------
 131
 132 #Add existing ArvadosFile or Subcollection to a collection
 133
 134 folder <- Subcollection$new("src")
 135 file <- ArvadosFile$new("main.cpp")
 136 folder$add(file)
 137
 138 collection$add(folder, "cpp")
 139
 140 #This examples will add file "main.cpp" in "./cpp/src/" folder if folder exists.
 141 #If subcollection contains more files or folders they will be added recursively.
 142
 143 --------------------------------------------------------------------------------------------------------------------------------
 144
 145 #Write to existing file (Override current content of the file)
 146
 147 arvadosFile <- collection$get("location/to/my/file.cpp")
 148
 149 arvadosFile$write("This is new file content")
 150
 151 --------------------------------------------------------------------------------------------------------------------------------
 152
 153 #Delete file from a collection
 154
 155 file <- collection$get("location/to/my/file.cpp")
 156
 157 collection$remove(file)
 158
 159 #Or
 160
 161 collection$remove("location/to/my/file.cpp")
 162
 163 #Both examples will remove file "file.cpp" from a collection
 164 #You can remove both Subcollection and ArvadosFile
 165 #If subcollection contains more files or folders they will be removed recursively.
 166
 167 #You can also remove multiple files
 168
 169 collection$remove(c("path/to/my/file.cpp", "path/to/other/file.cpp"))
 170
 171 #Delete file or folder from a Subcollection
 172
 173 subcollection <- collection$get("mySubcollection/")
 174 subcollection$remove("fileInsideSubcollection.exe")
 175 subcollection$remove("folderInsideSubcollection/")
 176
 177 --------------------------------------------------------------------------------------------------------------------------------
 178
 179 #Move file or folder inside collection
 180
 181 file <- collection$get("location/to/my/file.cpp")
 182
 183 file$move("destination/file.cpp")
 184
 185 #Or subcollections
 186
 187 subcollection <- collection$get("location/to/folder")
 188
 189 subcollection$move("destination/folder")
 190
 191 #Make sure to include folder name in destination
 192 #For example
 193 #file$move("destination/") will not work
 194
 195
 196 --------------------------------------------------------------------------------------------------------------------------------
 197 WORKING WITH ARVADOS PROJECTS
 198 --------------------------------------------------------------------------------------------------------------------------------
 199
 200 #Get a project:
 201
 202 arv$getProject("uuid")
 203
 204 --------------------------------------------------------------------------------------------------------------------------------
 205
 206 #List projects:
 207
 208 projects <- arv$listProjects(list(list("owner_uuid", "=", "aaaaa-j7d0g-ccccccccccccccc"))) # list subprojects of a project
 209 arv$listProjects(list(list("name","like","Example%"))) # list projects which have names beginning with Example
 210
 211 --------------------------------------------------------------------------------------------------------------------------------
 212
 213 #Delete a project:
 214
 215 deletedProject <- arv$deleteProject("uuid")
 216
 217 --------------------------------------------------------------------------------------------------------------------------------
 218
 219 #Update project:
 220
 221 updatedProject <- arv$updateProject("uuid", list(name = "new_name", description = "new description"))
 222
 223 --------------------------------------------------------------------------------------------------------------------------------
 224
 225 #Create project:
 226
 227 createdProject <- arv$createProject(list(name = "project_name", description = "project description"))
 228
 229
 230 --------------------------------------------------------------------------------------------------------------------------------
 231 BUILDING THE ARVADOS SDK TARBALL
 232 --------------------------------------------------------------------------------------------------------------------------------
 233
 234
 235 cd arvados/sdk
 236 R CMD build R
 237
 238 This will create a tarball of the Arvados package in the current directory.