X-Git-Url: https://git.arvados.org/arvados.git/blobdiff_plain/62a2ccba46cb5b83e510e727afa44eee2e893676..44ab8ee44302102a7cd5289ef7336d7a94594558:/sdk/R/README diff --git a/sdk/R/README b/sdk/R/README index 2e2298e187..8a0c31dce6 100644 --- a/sdk/R/README +++ b/sdk/R/README @@ -1,63 +1,84 @@ R SDK for Arvados -Examples of usage: +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. + +INSTALLATION + +1. Install the dependencies + + > install.packages(c('R6', 'httr', 'stringr', 'jsonlite', 'curl', 'XML')) + +If needed, you may have to install the supporting packages first. On Linux, these are: + + libxml2-dev, libssl-dev, libcurl4-gnutls-dev or libcurl4-openssl-dev + +2. Install the ArvardosR package -#Initialize API: + > install.packages('/path/to/ArvadosR_0.0.2.tar.gz', repos = NULL, type="source", dependencies = TRUE) -arv <- Arvados$new("insert_token", "insert_host_name") + +EXAMPLES OF USAGE + + +#Load Library and Initialize API: + +library('ArvadosR') +arv <- Arvados$new() # uses environment variables ARVADOS_API_TOKEN and ARVADOS_API_HOST +arv <- Arvados$new("your Arvados token", "example.arvadosapi.com") -------------------------------------------------------------------------------------------------------------------------------- -#Get collection: +#Get a collection: arv$getCollection("uuid") -------------------------------------------------------------------------------------------------------------------------------- #List collections: +collectionList <- arv$listCollections(list(list("name", "like", "Test%"))) # offset of 0 and default limit of 100 +collectionList <- arv$listCollections(list(list("name", "like", "Test%")), limit = 10, offset = 2) -collectionList <- arv$listCollections(list("uuid", "=" "aaaaa-bbbbb-ccccccccccccccc"), limit = 10, offset = 2) +collectionList$items_available # count of total number of items (may be more than returned due to paging) +collectionList$items # items which match the filter criteria + +#Next example will list all collections even when the number of items is greater than maximum API limit + +collectionList <- arv$listAllCollections(list(list("name", "like", "Test%"))) -------------------------------------------------------------------------------------------------------------------------------- -#Delete collection: +#Delete a collection: deletedCollection <- arv$deleteCollection("uuid") -------------------------------------------------------------------------------------------------------------------------------- -#Update collection: +#Update a collection's metadata: -updatedCollection <- arv$updateCollection("uuid", list((name = "new_name", description = "new_desciption"))) +updatedCollection <- arv$updateCollection("uuid", list(name = "New name", description = "New description")) -------------------------------------------------------------------------------------------------------------------------------- #Create collection: -cratedCollection <- arv$createCollection(list(list(name = "new_name", description = "new_desciption"))) +createdCollection <- arv$createCollection(list(name = "Example", description = "This is a test collection")) --------------------------------------------------------------------------------------------------------------------------------- -------------------------------------------------------------------------------------------------------------------------------- - -#Collection content manipulation: - --------------------------------------------------------------------------------------------------------------------------------- - +COLLECTION CONTENT MANIPULATION -------------------------------------------------------------------------------------------------------------------------------- #Create collection object: -arv <- Arvados$new("insert_token", "insert_host_name") collection <- Collection$new(arv, "uuid") -------------------------------------------------------------------------------------------------------------------------------- -#Get file/folder content as character vector +#Get list of files -collection$getFileContent() +collection$getFileListing() -------------------------------------------------------------------------------------------------------------------------------- @@ -71,13 +92,30 @@ arvadosSubcollection <- collection$get("location/to/my/directory/") -------------------------------------------------------------------------------------------------------------------------------- +#Read a table + +arvadosFile <- collection$get("myinput.txt") +arvConnection <- arvadosFile$connection("r") +mytable <- read.table(arvConnection) + +#Write a table + +arvadosFile <- collection$create("myoutput.txt") +arvConnection <- arvadosFile$connection("w") +write.table(mytable, arvConnection) +arvadosFile$flush() + +-------------------------------------------------------------------------------------------------------------------------------- + #Read whole file or just a portion of it. -fileContent <- arvadosFile$read(offset = 1024, length = 512) +fileContent <- arvadosFile$read() +fileContent <- arvadosFile$read("text") +fileContent <- arvadosFile$read("raw", offset = 1024, length = 512) -------------------------------------------------------------------------------------------------------------------------------- -#Get ArvadosFile or Subcollection size +#Get ArvadosFile or Subcollection size size <- arvadosFile$getSizeInBytes() size <- arvadosSubcollection$getSizeInBytes() @@ -86,29 +124,26 @@ size <- arvadosSubcollection$getSizeInBytes() #Create new file in a collection -#Call structure - -collection$add(arvadosFileOrSubcollectionOrFileName, optionalRelativePath) +collection$create(fileNames, optionalRelativePath) #Example -collection$add("main.cpp", "cpp/src/") +mainFile <- collection$create("main.cpp", "cpp/src/") +fileList <- collection$create(c("main.cpp", lib.dll), "cpp/src/") -#or +-------------------------------------------------------------------------------------------------------------------------------- + +#Add existing ArvadosFile or Subcollection to a collection folder <- Subcollection$new("src") -file <- ArvadosFile$new("main.cpp") +file <- ArvadosFile$new("main.cpp") folder$add(file) collection$add(folder, "cpp") -#Both examples will add file "main.cpp" in "./cpp/src/" folder if folder exists. +#This examples will add file "main.cpp" in "./cpp/src/" folder if folder exists. #If subcollection contains more files or folders they will be added recursively. -#You can also add multiple files - -collection$add(c("path/to/my/file.cpp", "path/to/other/file.cpp")) - -------------------------------------------------------------------------------------------------------------------------------- #Write to existing file (Override current content of the file) @@ -121,26 +156,47 @@ arvadosFile$write("This is new file content") #Delete file from a collection -file <- collection$get("location/to/my/file.cpp") - -file$removeFromCollection() - -#Or - -collection$remove(file) +collection$remove("location/to/my/file.cpp") -#Both examples will remove file "file.cpp" from a collection +#You can remove both Subcollection and ArvadosFile #If subcollection contains more files or folders they will be removed recursively. #You can also remove multiple files collection$remove(c("path/to/my/file.cpp", "path/to/other/file.cpp")) +#Delete file or folder from a Subcollection + +subcollection <- collection$get("mySubcollection/") +subcollection$remove("fileInsideSubcollection.exe") +subcollection$remove("folderInsideSubcollection/") + -------------------------------------------------------------------------------------------------------------------------------- +#Move file or folder inside collection + +#Directley from collection + +collection$move("folder/file.cpp", "file.cpp") + +#Or from file + +file <- collection$get("location/to/my/file.cpp") +file$move("newDestination/file.cpp") + +#Or from subcollection + +subcollection <- collection$get("location/to/folder") +subcollection$move("newDestination/folder") + +#Make sure to include new file name in destination +#In second example file$move("newDestination/") will not work + +-------------------------------------------------------------------------------------------------------------------------------- +WORKING WITH ARVADOS PROJECTS -------------------------------------------------------------------------------------------------------------------------------- -#Get project: +#Get a project: arv$getProject("uuid") @@ -148,11 +204,16 @@ arv$getProject("uuid") #List projects: -projects <- arv$listProjects(list("uuid", "=" "aaaaa-bbbbb-ccccccccccccccc"), limit = 10, offset = 2) +projects <- arv$listProjects(list(list("owner_uuid", "=", "aaaaa-j7d0g-ccccccccccccccc"))) # list subprojects of a project +arv$listProjects(list(list("name","like","Example%"))) # list projects which have names beginning with Example + +#Next example will list all projects even when the number of items is greater than maximum API limit + +collectionList <- arv$listAllProjects(list(list("name","like","Example%"))) -------------------------------------------------------------------------------------------------------------------------------- -#Delete project: +#Delete a project: deletedProject <- arv$deleteProject("uuid") @@ -160,12 +221,21 @@ deletedProject <- arv$deleteProject("uuid") #Update project: -updatedProject <- arv$updateProject("uuid", list((name = "new_name", description = "new_desciption"))) +updatedProject <- arv$updateProject("uuid", list(name = "new_name", description = "new description")) -------------------------------------------------------------------------------------------------------------------------------- #Create project: -cratedProject <- arv$createProject(list(list(name = "project_name", description = "project_desciption"))) +createdProject <- arv$createProject(list(name = "project_name", description = "project description")) + -------------------------------------------------------------------------------------------------------------------------------- +BUILDING THE ARVADOS SDK TARBALL +-------------------------------------------------------------------------------------------------------------------------------- + + +cd arvados/sdk +R CMD build R + +This will create a tarball of the Arvados package in the current directory.