Skip to contents

Getting Started

Source: vignettes/proofr.Rmd
proofr.Rmd

Load proofr

Authenticate with the PROOF API

Run the function proof_authenticate(), which calls the PROOF API with your HutchNet username and password, and returns an API token (an alphanumeric string).

We strongly recommend to not supply password to proof_authenticate as plain text like, and instead pull in your password from an environment variable stored outside of R. For a description of different options for where to store your HutchNet password see the R Startup chapter in the book What They Forgot to Teach You About R.

my_proof_token <- proof_authenticate(username = "username", password = Sys.getenv("HUTCHNET_PWD"))
my_proof_token
#> xyGKibGctQ92rmMKKb39q43XgPxGCmrWoX7NZtamTjDP

(note: the above token is not a real token)

Alternatively, save your API token directly as an environment variable named PROOF_TOKEN so that it can be used by other proofr functions without exposing your token in your code. To do so, run the following:

Sys.setenv("PROOF_TOKEN" = proof_authenticate("username", "password"))

Instead of just setting your token for the current R session, you can set a token that can be used across sessions by putting your token in a file that is read in by R when it starts up. Create a ~/.Renviron file (if it doesn’t exist already) that contains PROOF_TOKEN=your-token-here and it will be available in your R session. Run chmod 0400 ~/.Renviron to make sure only you can see its contents. Make sure to restart your R session after any changes to this file so the changes are picked up.

Start a PROOF Server

Start a PROOF server using the proof_start() function:

Note: proofr assumes you only have one server running; if you’ve started a server using the app, you’ll need to stop that server before starting one in R via proofr.

Get metadata about the PROOF server you have started, including the URL of the API, using wait=TRUE so that it doesn’t return data until the server is fully ready to use.

metadata <- proof_status(wait = TRUE)
cromwell_url <- metadata$cromwellUrl
cromwell_url

rcromwell setup

Load rcromwell

if (!requireNamespace("rcromwell", quietly=TRUE)) {
  install.packages("pak")
  pak::pak("getwilds/rcromwell")
}
library(rcromwell)
library(httr)

There are two options for setting the URL in rcromwell.

The first option is to set the Cromwell server URL to be recognized by rcromwell with cromwell_config

cromwell_config(cromwell_url)

The other option is to pass the url to each function, for example:

cromwell_jobs(url = cromwell_url)

In addition to setting the Cromwell URL, your PROOF API token is also required for HTTP requests to your server. After getting your PROOF token you can set it as the env var PROOF_TOKEN, or pass it to the rcromwell functions, for example:

cromwell_jobs(url = cromwell_url, token = my_proof_token)

Interact with the Cromwell server

As an example, cromwell_version() checks the version of your Cromwell server

cromwell_version()
#> $cromwell
#> [1] "84"

See the many functions in rcromwell documentation.

Done!

You’re now setup to interact with your Cromwell server. See the rcromwell package docs to get started.