neuprint_login: Connect to/authenticate with a neuPrint server and its Neo4j...

In natverse/neuprintr: R Client Utilities for Interacting with the neuPrint Connectome Analysis Service

Connect to/authenticate with a neuPrint server and its Neo4j database, returning a neuPrint connection object

Description

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 environment variables of the form "neuprint_*" (see details).

If your server has more than one dataset available, it is also a good idea to set the default neuPrint dataset you want to work with, either by passing an explicit dataset argument (to neuprint_login or neuprint_connection) when first making the connection or by setting a neuprint_dataset environment variable.

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.

Usage

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

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

Arguments

server	the neuprint server
token	your personal Bearer token
dataset	A default dataset to use with this connection (you can still override this using the dataset argument of other neuprintr functions.)
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

Details

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.

Value

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.

Token based authentication

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 have 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.

Environment variables

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 neuprintr 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://neuprint.janelia.org"
  neuprint_token =
  "asBatEsiOIJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJlbWFpbCI6ImFsZXhhbmRlci5zaGFrZWVsLmJhdGVzQGdtYWlsLmNvbSIsImxldmVsIjoicmVhZHdyaXRlIiwiaW1hZ2UtdXJsIjoiaHR0cHM7Ly9saDQuZ29vZ2xldXNlcmNvbnRlbnQuY29tLy1QeFVrTFZtbHdmcy9BQUFBQUFBQUFBDD9BQUFBQUFBQUFBQS9BQ0hpM3JleFZMeEI4Nl9FT1asb0dyMnV0QjJBcFJSZlBRL21vL3Bob3RvLapwZz9zej01MCIsImV4cCI6MTczMjc1MjU2HH0.jhh1nMDBPl5A1HYKcszXM518NZeAhZG9jKy3hzVOWEU"

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 have logged in with an approved Google account.

The use of the neuprint_dataset environment variable is optional and only recommended when your default neuprint server has more than one dataset. This default will not apply to connections that refer to a server other than the one specified by the neuprint_server environment variable.

neuprint_dataset = "hemibrain:v1.0"

Options

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://neuprint.janelia.org', neuprint_token = "asBatEsiOIJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJlbWFpbCI6ImFsZXhhbmRlci5zaGFrZWVsLmJhdGVzQGdtYWlsLmNvbSIsImxldmVsIjoicmVhZHdyaXRlIiwiaW1hZ2UtdXJsIjoiaHR0cHM7Ly9saDQuZ29vZ2xldXNlcmNvbnRlbnQuY29tLy1QeFVrTFZtbHdmcy9BQUFBQUFBQUFBDD9BQUFBQUFBQUFBQS9BQ0hpM3JleFZMeEI4Nl9FT1asb0dyMnV0QjJBcFJSZlBRL21vL3Bob3RvLapwZz9zej01MCIsImV4cCI6MTczMjc1MjU2HH0.jhh1nMDBPl5A1HYKcszXM518NZeAhZG9jKy3hzVOWEU")

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

Curl options

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⁠

See Also

options, Startup, neuprint_datasets

Examples

## Not run: 
## example explicitly specifying connection options
conn = neuprint_login(server= "neuprint.janelia.org",
  token= "asBatEsiOIJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJlbWFpbCI6ImFsZXhhbmRlci5za
  GFrZWVsLmJhdGVzQGdtYWlsLmNvbSIsImxldmVsIjoicmVhZHdyaXRlIiwiaW1hZ2UtdXJsIj
  oiaHR0cHM7Ly9saDQuZ35vZ2xldXNlcmNvbnRlbnQuY29tLy1QeFVrTFZtbHdmcy9BQUFBQUF
  BQUFBDD9BQUFBQUFBQUFBQS9BQ0hpM3JleFZMeEI4Nl9FT1asb0dyMnV0QjJBcFJSZlBRL21v
  L3Bob3RvLapwZz9zej01MCIsImV4cCI6MTczMjc1MjM2HH0.jhh1nMDBPl5A1HYKcszXM518NZ
  eAhZG9jKy3hzVOWEU")


## 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)

# make connection to second server
conn2=neuprint_login(server="https://server2.org",
  token=Sys.getenv('NPSERVER2'))

# specify a default dataset (only required when >1 dataset available)
conn2=neuprint_login(server="https://server2.org",
  token=Sys.getenv('NPSERVER2'), dataset="hemibrain")

# make a connection to the same server but using a different dataset
# this may be more convenient than specifying the dataset argument
conn3=neuprint_login(conn2, dataset="vnc")

## End(Not run)

natverse/neuprintr documentation built on Sept. 15, 2023, 6:59 a.m.