neuprintr: R client utilities for interacting with the neuPrint connectome analysis service

Description Usage Arguments Details Value Token based authentication Environment variables Options Curl options See Also Examples

View source: R/conn.R

neuprint_login allows you to login to a neuPrint server specified by a neuprint_connection object. If such an object is not specified, then the last successful connection in this R session is reused if possible otherwise a new connection object is created using options of the form "neuprint_*" (see details). It is also very useful to set the default neuPrint dataset you want to work with, if the server hosts multiple datasets, see details.

The connection object returned by neuprint_login (or cached when Cache=TRUE, the default) can then be used for future requests to the neuPrint server by get/query/fetch functions.

neuprint_connection(server = NULL, token = NULL, conn = NULL,
  config = httr::config())

neuprint_login(conn = NULL, Cache = TRUE, Force = FALSE, ...)

`server`	the neuprint server
`token`	your personal Bearer token
`conn`	a neuprintr connection object
`config`	an `httr::config` object that can be used to set advanced curl options (e.g. additional authentication, proxy settings etc). See Curl options section and Examples.
`Cache`	Whether to cache open connections at login so that they can be reused automatically.
`Force`	Whether to force a new login to the CATMAID server (default `FALSE`)
`...`	methods passed to neuprint_connection

After successful login, the neuprint_connection object will contain a cookie field that includes a sessionid that is required for subsequent GET/POST operations using the package httr. When Cache=TRUE (the default) the open connection object is cached and will be used when EITHER neuprint_login is called with enough information to indicate that the same server is desired OR (when no information about the server is passed to neuprint_login) the last opened connection will be used. A new connection can be made using Force = TRUE, which is advisable as a first call for debugging if you are having issues querying the server.

a neuprint_connection object that can be used to make authenticated https requests to a neuPrint server, specifically by making use of its $config field.

neuPrint requires Bearer token based authentication. You can get your token by going to your neuPrint server's webpage and right clicking on the icon showing your Google account on the top right corner, and selecting AUTH_TOKEN, or often at your server's address /token, once you havw signed in via your approved Google account. Contact the server's administrators if you do not have access, but think that you should. You can then set the catmaid.token package option, but no

Note that you must NOT reveal this token e.g. by checking it into a version controlled script as it gives complete access to your neuPrint account.

You will very likely want to set the following environment variables in your .Renviron file (see Startup for details). This file is read by R on startup. In this way the catmaid package will automatically login to your preferred neuPrint server. Note that environment variables will also be inherited by child R sessions. This means for example that they will be available when running knitr reports, tests or R CMD Check from RStudio. In order to edit your R.profile or R.environ files easily and directly, try using usethis::edit_r_environ() and usethis::edit_r_profile()

neuprint_server
neuprint_token
neuprint_dataset

An example .Renviron file might look like:

neuprint_server = "https://emdata1.int.janelia.org:11000"
  neuprint_token =
  "asBatEsiOIJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJlbWFpbCI6ImFsZXhhbmRlci5zaGFrZWVsLmJhdGVzQGdtYWlsLmNvbSIsImxldmVsIjoicmVhZHdyaXRlIiwiaW1hZ2UtdXJsIjoiaHR0cHM7Ly9saDQuZ29vZ2xldXNlcmNvbnRlbnQuY29tLy1QeFVrTFZtbHdmcy9BQUFBQUFBQUFBDD9BQUFBQUFBQUFBQS9BQ0hpM3JleFZMeEI4Nl9FT1asb0dyMnV0QjJBcFJSZlBRL21vL3Bob3RvLapwZz9zej01MCIsImV4cCI6MTczMjc1MjU2HH0.jhh1nMDBPl5A1HYKcszXM518NZeAhZG9jKy3hzVOWEU"
   neuprint_dataset = "hemibrain"

and must finish with a return at the end of the last line. Your neuprint_token is unique to you and must be obtained from a neuPrint web page once you havw logged in with an approved Google account.

Although setting environment variables is the recommended approach, you can also set R startup options e.g. in your .Rprofile to specify default neuPrint login options including your personal access token. The startup options have the same names as the environment variables listed above, so you can place code along the lines of:

options(neuprint_server = 'https://emdata1.int.janelia.org:11000', neuprint_token = "asBatEsiOIJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJlbWFpbCI6ImFsZXhhbmRlci5zaGFrZWVsLmJhdGVzQGdtYWlsLmNvbSIsImxldmVsIjoicmVhZHdyaXRlIiwiaW1hZ2UtdXJsIjoiaHR0cHM7Ly9saDQuZ29vZ2xldXNlcmNvbnRlbnQuY29tLy1QeFVrTFZtbHdmcy9BQUFBQUFBQUFBDD9BQUFBQUFBQUFBQS9BQ0hpM3JleFZMeEI4Nl9FT1asb0dyMnV0QjJBcFJSZlBRL21vL3Bob3RvLapwZz9zej01MCIsImV4cCI6MTczMjc1MjU2HH0.jhh1nMDBPl5A1HYKcszXM518NZeAhZG9jKy3hzVOWEU", neuprint_dataset = 'hemibrain' )

in your .Rprofile (see Startup for details). Note that it is important to have a final return at the end of your .Rprofile file.

neuprintr uses the curl library provided by the httr and curl packages to carry out remote requests. You can set curl options by passing an httr::config object that can be used to set advanced curl options (e.g. additional authentication, proxy settings etc). See handle and curl_options for a full list of possible options.

You can also set default curl options using environment variables with names of the form neuprint_curl_<curloption>. For example the following entry in you Renviron file will set the curl ssl_verifyhost option:

neuprint_curl_ssl_verifyhost=0

options, Startup, neuprint_datasets

## Not run: 
## example explicitly specifying connection options
conn = neuprint_login(server= "https://emdata1.int.janelia.org:11000",
  token= "asBatEsiOIJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJlbWFpbCI6ImFsZXhhbmRlci5zaGFrZWVsLmJhdGVzQGdtYWlsLmNvbSIsImxldmVsIjoicmVhZHdyaXRlIiwiaW1hZ2UtdXJsIjoiaHR0cHM7Ly9saDQuZ29vZ2xldXNlcmNvbnRlbnQuY29tLy1QeFVrTFZtbHdmcy9BQUFBQUFBQUFBDD9BQUFBQUFBQUFBQS9BQ0hpM3JleFZMeEI4Nl9FT1asb0dyMnV0QjJBcFJSZlBRL21vL3Bob3RvLapwZz9zej01MCIsImV4cCI6MTczMjc1MjU2HH0.jhh1nMDBPl5A1HYKcszXM518NZeAhZG9jKy3hzVOWEU")


## examples assuming that neuprint_* environment variables/options are set
conn = neuprint_login()

## using env vars + config to set advanced curl options
neuprint_login(config=httr::config(ssl_verifyhost=0))

## now do stuff with the connection like
available.datasets = neuprint_datasets(conn=conn)

## which, if you have edited your R.profile / R.environ, should produce the same results as
available.datasets = neuprint_datasets(conn=NULL)

## End(Not run)