Power your digital lab and reduce the time from theory to discovery using the Agave Science-as-a-Service API Platform. Agave provides hosted services that allow researchers to manage data, conduct experiments, and publish and share results from anywhere at any time.
The Agave R client SDK is based off the vanilla REST API client code generated by the swagger-codegen project. Additional scripts were added to ease authentication and authorization, session management, serialization, and improve syntax.
You'll need the devtools
package in order to build the API.
Make sure you have a proper CRAN repository from which you can download packages.
Install the devtools
package with the following command.
> if(!require(devtools)) { install.packages("devtools") }
> if(!require(devtools)) { install.packages("plyr") }
If you would like to rebuild the documentation, you will need to install roxygen2.
> if(!require(roxygen2)) { install.packages("roxygen2") }
To install the package directly from the master branch in Github
> library(devtools)
> install_github("agaveplatform/r-sdk")
Make sure you set the working directory to the repository home directory. Then execute
> library(devtools)
> install(".")
========================
This repository includes a Dockerfile
and a docker-compose.yml
file, which allows a zero installation version of rAgave
in RStudio.
The only requirement is Docker and Docker Compose. Please consult the official Docker website for installation instructions for your system.
To bring up your development environment, clone this repository and execute docker-compose
as follows:
$ git clone https://github.com/agaveplatform/r-sdk.git agave-r-sdk
$ cd agave-r-sdk
$ docker-compose build
$ docker-compose up
Navigate to http://localhost:8787 and access the RStudio server
with username and password "rstudio". The notebook R-example.Rmd
contains a full example of use.
Import the library into your current session namespace.
> library(rAgave)
Now we can create an Agave
instance pointing to your tenant:
> library(rAgave)
> api = Agave$new(baseUrl="https://public.agaveapi.org",
username="myusername",
password="mypassword")
Once the object is instantiated, interact with it according to the methods in the API documentation.
For example, create a new client with:
> clientData <- Client$new(clientName="my_client")
> api$clientInfo <- api$clients$create(body=clientData)
> api$store()
You may also pass in a list, if preferred, over the object model
> api$clientInfo <- api$clients$create(body=list(clientName="my_client"))
> api$store()
Access any endpoint with:
> api$systems$listSystems()
> api$jobs$submitJob(body=Job$new(appId="head-1.0u1"))
Once a client is created, it is used by default to access the API.
To make use of an existing client, pass the client's credentials into the Agave constructor:
> library("rAgave")
> api = Agave$new(baseUrl="https://public.agaveapi.co",
username="myusername", password="mypassword",
clientKey="123", clientSecret="abc")
If you do not pass in any client, credential, token, or tenant information in your constructor, the SDK will look for those values in your runtime environment. The following table lists the environment variables corresponding to each constructor argument in the SDK.
| Argument | Environment Variable | |--------------|---------------------------------------| | baseUrl | AGAVE_BASE_URL, AGAVE_TENANT_BASE_URL | | username | AGAVE_USERNAME | | password | AGAVE_PASSWORD | | clientKey | AGAVE_CLIENT_KEY | | clientSecret | AGAVE_CLIENT_SECRET | | tenant | AGAVE_TENANT | | cacheDir | AGAVE_CACHE_DIR | | accessToken | AGAVE_ACCESS_TOKEN | | refreshToken | AGAVE_REFRESH_TOKEN |
The following code would produce the identical result as the previous example.
> library("rAgave")
> Sys.setenv(AGAVE_BASE_URL = "https://public.agaveapi.co",
+ AGAVE_USERNAME = "myusername",
+ AGAVE_PASSWORD = "mypassword",
+ AGAVE_CLIENT_KEY = "123",
+ AGAVE_CLIENT_SECRET = "abc")
> api = Agave$new()
If you do not know the baseUrl
of your tenant, you can simply provide the tenant code. The following example will initialize instances of the SDK for the Agave Public tenant, Cyverse Tenant, and DesignSafe tenants respectively.
> library("rAgave")
> api = Agave$new(tenant="agave.prod")
> api = Agave$new(tenant="iplantc.org")
> api = Agave$new(tenant="designsafe")
If you do not know the code or url of your tenant, you can query the Tenants API to find a list of all the available tenants.
> library("rAgave")
> api <- Agave$new()
> tenants <- api$tenants$list(responseType="df")
> tenants$code
[1] agave.prod araport.org designsafe iplantc.org irec
[6] irmacs sd2e sgci tacc.prod vdjserver.org
> api$tenantInfo <- tenants[[1]]
Alternatively, the SDK will attempt to recover the client credentials from a predictable location disk. The default cache directory is $HOME/.agave
. You can configure the location of the cache directory when instantiating a new Agave
object:
> library("rAgave")
> api = Agave$new(cacheDir="/Dropbox/agave/cache")
The format of the cache file is recognized by all Agave SDK, so you can freely move across multiple SDK without having to reauthenticate each time.
Your password will never be written to the cache file.
rAgave will automatically update the cache file any time you create or update your client or authenticate. Thus, subsequent instantiations can be streamlined to use the no-arg constructor as rAgave will automatically refresh your access token for you.
> api = Agave$new()
rAgave leverages the futile.logger
package to provide a custom logging output similar to log4j. You can enabled logging at runtime by specifying the logLevel
parameter in the constructor. The following log levels are predefined as constants: TRACE, DEBUG, INFO, WARN, FATAL. The log level is set to FATAL by default.
> api = Agave$new(logLevel = INFO)
You can also change the log level at runtime by upating the logLevel
attibute of an Agave class instance.
> api = Agave$new()
> api$logLevel <- TRACE
> profile <- api$profiles$getDetails()
> api$logLevel <- DEBUG
> profile <- api$jobs$listJobs()
> api$logLevel <- FATAL
When enabled, logs will be written to agave.log
in the currrent directory (getwd()
). You can specify an alternative location by specifying the logFilePath
parameter in the constructor.
> api = Agave$new(logFilePath = "/var/log/rAgave.log", logLevel = INFO)
The Agave Platform and rAgave are licensed under the BSD 3-Clause license.
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.