X-Git-Url: https://git.arvados.org/arvados.git/blobdiff_plain/8a2035547ad8bf6abad6a4a03bb0b59211a00932..7407f41105f8000bb3908d41a31daaf3a30d9440:/sdk/R/README.Rmd

diff --git a/sdk/R/README.Rmd b/sdk/R/README.Rmd
index 098bfe19a5..c1d6c7cf4f 100644
--- a/sdk/R/README.Rmd
+++ b/sdk/R/README.Rmd
@@ -1,3 +1,7 @@
+[comment]: # (Copyright (c) The Arvados Authors. All rights reserved.)
+[comment]: # ()
+[comment]: # (SPDX-License-Identifier: CC-BY-SA-3.0)
+
 ## R SDK for Arvados
 
 This SDK focuses on providing support for accessing Arvados projects, collections, and the files within collections.
@@ -5,294 +9,327 @@ The API is not final and feedback is solicited from users on ways in which it co
 
 ### Installation
 
-```install.packages("ArvadosR", repos=c("http://r.arvados.org", getOption("repos")["CRAN"]), dependencies=TRUE)```
+```{r include=FALSE}
+knitr::opts_chunk$set(eval=FALSE)
+```
+
+```{r}
+install.packages("ArvadosR", repos=c("http://r.arvados.org", getOption("repos")["CRAN"]), dependencies=TRUE)
+```
 
 Note: on Linux, you may have to install supporting packages.
 
 On Centos 7, this is:
 
-```yum install libxml2-devel openssl-devel curl-devel```
+```{bash}
+yum install libxml2-devel openssl-devel curl-devel
+```
 
 On Debian, this is:
 
-```apt-get install build-essential libxml2-dev libssl-dev libcurl4-gnutls-dev```
+```{bash}
+apt-get install build-essential libxml2-dev libssl-dev libcurl4-gnutls-dev
+```
+
+Minimum R version required to run ArvadosR is 3.3.0.
 
 
 ### Usage
 
 #### Initializing API
 
-```{r include=FALSE}
-knitr::opts_chunk$set(eval = FALSE)
-```
-
 * Load Library and Initialize API:
 
-    ```{r}
-    library('ArvadosR')
-    # use environment variables ARVADOS_API_TOKEN and ARVADOS_API_HOST
-    arv <- Arvados$new()
+```{r}
+library('ArvadosR')
+# use environment variables ARVADOS_API_TOKEN and ARVADOS_API_HOST
+arv <- Arvados$new()
 
-    # provide them explicitly
-    arv <- Arvados$new("your Arvados token", "example.arvadosapi.com")
-    ```
+# provide them explicitly
+arv <- Arvados$new("your Arvados token", "example.arvadosapi.com")
+```
 
-    Optionally, add numRetries parameter to specify number of times to retry failed service requests.
-    Default is 0.
+Optionally, add numRetries parameter to specify number of times to retry failed service requests.
+Default is 0.
 
-    ```{r}
-    arv <- Arvados$new("your Arvados token", "example.arvadosapi.com", numRetries = 3)
-    ```
+```{r}
+arv <- Arvados$new("your Arvados token", "example.arvadosapi.com", numRetries = 3)
+```
 
-    This parameter can be set at any time using setNumRetries
+This parameter can be set at any time using setNumRetries
 
-    ```{r}
-    arv$setNumRetries(5)
-    ```
+```{r}
+arv$setNumRetries(5)
+```
 
 
 #### Working with collections
 
 * Get a collection:
 
-    ```{r}
-    collection <- arv$getCollection("uuid")
-    ```
+```{r}
+collection <- arv$collections.get("uuid")
+```
 
 * List collections:
 
-    ```{r}
-    # offset of 0 and default limit of 100
-    collectionList <- arv$listCollections(list(list("name", "like", "Test%")))
+```{r}
+# offset of 0 and default limit of 100
+collectionList <- arv$collections.list(list(list("name", "like", "Test%")))
 
-    collectionList <- arv$listCollections(list(list("name", "like", "Test%")), limit = 10, offset = 2)
-    ```
+collectionList <- arv$collections.list(list(list("name", "like", "Test%")), limit = 10, offset = 2)
+```
 
-    ```{r}
-    # count of total number of items (may be more than returned due to paging)
-    collectionList$items_available
+```{r}
+# count of total number of items (may be more than returned due to paging)
+collectionList$items_available
 
-    # items which match the filter criteria
-    collectionList$items
-    ```
+# items which match the filter criteria
+collectionList$items
+```
 
 * List all collections even if the number of items is greater than maximum API limit:
 
-    ```{r}
-    collectionList <- arv$listAllCollections(list(list("name", "like", "Test%")))
-    ```
+```{r}
+collectionList <- listAll(arv$collections.list, list(list("name", "like", "Test%")))
+```
 
 * Delete a collection:
 
-    ```{r}
-    deletedCollection <- arv$deleteCollection("uuid")
-    ```
+```{r}
+deletedCollection <- arv$collections.delete("uuid")
+```
 
 * Update a collection's metadata:
 
-    ```{r}
-    updatedCollection <- arv$updateCollection("uuid", list(name = "New name", description = "New description"))
-    ```
+```{r}
+updatedCollection <- arv$collections.update(list(name = "New name", description = "New description"), "uuid")
+```
 
 * Create collection:
 
-    ```{r}
-    createdCollection <- arv$createCollection(list(name = "Example", description = "This is a test collection"))
-    ```
+```{r}
+newCollection <- arv$collections.create(list(name = "Example", description = "This is a test collection"))
+```
 
 
 #### Manipulating collection content
 
 * Create collection object:
 
-    ```{r}
-    collection <- Collection$new(arv, "uuid")
-    ```
+```{r}
+collection <- Collection$new(arv, "uuid")
+```
 
 * Get list of files:
 
-    ```{r}
-    files <- collection$getFileListing()
-    ```
+```{r}
+files <- collection$getFileListing()
+```
 
 * Get ArvadosFile or Subcollection from internal tree-like structure:
 
-    ```{r}
-    arvadosFile <- collection$get("location/to/my/file.cpp")
-    ```
+```{r}
+arvadosFile <- collection$get("location/to/my/file.cpp")
+```
 
-    or
+or
 
-    ```{r}
-    arvadosSubcollection <- collection$get("location/to/my/directory/")
-    ```
+```{r}
+arvadosSubcollection <- collection$get("location/to/my/directory/")
+```
 
 * Read a table:
 
-    ```{r}
-    arvadosFile   <- collection$get("myinput.txt")
-    arvConnection <- arvadosFile$connection("r")
-    mytable       <- read.table(arvConnection)
-    ```
+```{r}
+arvadosFile   <- collection$get("myinput.txt")
+arvConnection <- arvadosFile$connection("r")
+mytable       <- read.table(arvConnection)
+```
 
 * Write a table:
 
-    ```{r}
-    arvadosFile   <- collection$create("myoutput.txt")
-    arvConnection <- arvadosFile$connection("w")
-    write.table(mytable, arvConnection)
-    arvadosFile$flush()
-    ```
+```{r}
+arvadosFile   <- collection$create("myoutput.txt")
+arvConnection <- arvadosFile$connection("w")
+write.table(mytable, arvConnection)
+arvadosFile$flush()
+```
 
 * Write to existing file (override current content of the file):
 
-    ```{r}
-    arvadosFile <- collection$get("location/to/my/file.cpp")
-    arvadosFile$write("This is new file content")
-    ```
+```{r}
+arvadosFile <- collection$get("location/to/my/file.cpp")
+arvadosFile$write("This is new file content")
+```
 
 * Read whole file or just a portion of it:
 
-    ```{r}
-    fileContent <- arvadosFile$read()
-    fileContent <- arvadosFile$read("text")
-    fileContent <- arvadosFile$read("raw", offset = 1024, length = 512)
-    ```
+```{r}
+fileContent <- arvadosFile$read()
+fileContent <- arvadosFile$read("text")
+fileContent <- arvadosFile$read("raw", offset = 1024, length = 512)
+```
 
 * Get ArvadosFile or Subcollection size:
 
-    ```{r}
-    size <- arvadosFile$getSizeInBytes()
-    ```
+```{r}
+size <- arvadosFile$getSizeInBytes()
+```
 
-    or
+or
 
-    ```{r}
-    size <- arvadosSubcollection$getSizeInBytes()
-    ```
+```{r}
+size <- arvadosSubcollection$getSizeInBytes()
+```
 
 * Create new file in a collection:
 
-    ```{r}
-    collection$create(fileNames, optionalRelativePath)
-    ```
+```{r}
+collection$create(files)
+```
 
-    Example:
+Example:
 
-    ```{r}
-    mainFile <- collection$create("main.cpp", "cpp/src/")
-    fileList <- collection$create(c("main.cpp", lib.dll), "cpp/src/")
-    ```
+```{r}
+mainFile <- collection$create("cpp/src/main.cpp")
+fileList <- collection$create(c("cpp/src/main.cpp", "cpp/src/util.h"))
+```
 
-* Add existing ArvadosFile or Subcollection to a collection:
+* Delete file from a collection:
 
-    ```{r}
-    folder <- Subcollection$new("src")
-    file   <- ArvadosFile$new("main.cpp")
-    folder$add(file)
-    ```
+```{r}
+collection$remove("location/to/my/file.cpp")
+```
 
-    ```{r}
-    collection$add(folder, "cpp")
-    ```
+You can remove both Subcollection and ArvadosFile.
+If subcollection contains more files or folders they will be removed recursively.
 
-    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 remove multiple files at once:
 
-* Delete file from a collection:
+```{r}
+collection$remove(c("path/to/my/file.cpp", "path/to/other/file.cpp"))
+```
 
-    ```{r}
-    collection$remove("location/to/my/file.cpp")
-    ```
+* Delete file or folder from a Subcollection:
 
-    You can remove both Subcollection and ArvadosFile.
-    If subcollection contains more files or folders they will be removed recursively.
+```{r}
+subcollection <- collection$get("mySubcollection/")
+subcollection$remove("fileInsideSubcollection.exe")
+subcollection$remove("folderInsideSubcollection/")
+```
 
-    You can also remove multiple files at once:
+* Move or rename a file or folder within a collection (moving between collections is currently not supported):
 
-    ```{r}
-    collection$remove(c("path/to/my/file.cpp", "path/to/other/file.cpp"))
-    ```
+Directly from collection
 
-* Delete file or folder from a Subcollection:
+```{r}
+collection$move("folder/file.cpp", "file.cpp")
+```
+
+Or from file
+
+```{r}
+file <- collection$get("location/to/my/file.cpp")
+file$move("newDestination/file.cpp")
+```
 
-    ```{r}
-    subcollection <- collection$get("mySubcollection/")
-    subcollection$remove("fileInsideSubcollection.exe")
-    subcollection$remove("folderInsideSubcollection/")
-    ```
+Or from subcollection
 
-* Move file or folder inside collection:
+```{r}
+subcollection <- collection$get("location/to/folder")
+subcollection$move("newDestination/folder")
+```
 
-    Directley from collection
+Make sure to include new file name in destination.
+In second example file$move("newDestination/") will not work.
 
-    ```{r}
-    collection$move("folder/file.cpp", "file.cpp")
-    ```
+* Copy file or folder within a collection (copying between collections is currently not supported):
 
-    Or from file
+Directly from collection
 
-    ```{r}
-    file <- collection$get("location/to/my/file.cpp")
-    file$move("newDestination/file.cpp")
-    ```
+```{r}
+collection$copy("folder/file.cpp", "file.cpp")
+```
 
-    Or from subcollection
+Or from file
 
-    ```{r}
-    subcollection <- collection$get("location/to/folder")
-    subcollection$move("newDestination/folder")
-    ```
+```{r}
+file <- collection$get("location/to/my/file.cpp")
+file$copy("destination/file.cpp")
+```
 
-    Make sure to include new file name in destination.
-    In second example file$move("newDestination/") will not work.
+Or from subcollection
+
+```{r}
+subcollection <- collection$get("location/to/folder")
+subcollection$copy("destination/folder")
+```
 
 #### Working with Aravdos projects
 
 * Get a project:
 
-    ```{r}
-    project <- arv$getProject("uuid")
-    ```
+```{r}
+project <- arv$projects.get("uuid")
+```
 
 * List projects:
 
-    ```{r}
-    # list subprojects of a project
-    projects <- arv$listProjects(list(list("owner_uuid", "=", "aaaaa-j7d0g-ccccccccccccccc")))
+```{r}
+list subprojects of a project
+projects <- arv$projects.list(list(list("owner_uuid", "=", "aaaaa-j7d0g-ccccccccccccccc")))
 
-    # list projects which have names beginning with Example
-    arv$listProjects(list(list("name","like","Example%")))
-    ```
+list projects which have names beginning with Example
+examples <- arv$projects.list(list(list("name","like","Example%")))
+```
 
 * List all projects even if the number of items is greater than maximum API limit:
 
-    ```{r}
-    collectionList <- arv$listAllProjects(list(list("name","like","Example%")))
-    ```
+```{r}
+projects <- listAll(arv$projects.list, list(list("name","like","Example%")))
+```
 
 * Delete a project:
 
-    ```{r}
-    deletedProject <- arv$deleteProject("uuid")
-    ```
+```{r}
+deletedProject <- arv$projects.delete("uuid")
+```
 
 * Update project:
 
-    ```{r}
-    updatedProject <- arv$updateProject("uuid", list(name = "new_name", description = "new description"))
-    ```
+```{r}
+updatedProject <- arv$projects.update(list(name = "new_name", description = "new description"), "uuid")
+```
 
 * Create project:
 
-    ```{r}
-    createdProject <- arv$createProject(list(name = "project_name", description = "project description"))
-    ```
+```{r}
+newProject <- arv$projects.update(list(name = "project_name", description = "project description"))
+```
+
+#### Help
+
+* View help page of Arvados classes by puting ? before class name:
+
+```{r}
+?Arvados
+?Collection
+?Subcollection
+?ArvadosFile
+```
+
+* View help page of any method defined in Arvados class by puting ? before method name:
+
+```{r}
+?collections.update
+?jobs.get
+```
 
 ### Building the ArvadosR package
 
-  ```
-  cd arvados/sdk && R CMD build R
-  ```
+```{bash}
+cd arvados/sdk && R CMD build R
+```
 
 This will create a tarball of the ArvadosR package in the current directory.