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