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